66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
# Design: Map Context Retrieval
|
|
|
|
## Status
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Phase | **Design** |
|
|
| Based on | [Spec](spec.md) |
|
|
| Next | Tasks |
|
|
|
|
## Design summary
|
|
|
|
This change adds a lightweight retrieval layer on top of paired project-map metadata. It should not require a new external storage system, vector store, or Engram dependency. Instead, it should scan root and directory indexes first, expand to rich maps and files from the strongest candidates, and emit an agent-friendly bundle.
|
|
|
|
## Likely implementation areas
|
|
|
|
- `pi-extension.ts` for the first-class tool surface
|
|
- `src/index.ts` for exports
|
|
- new retrieval module, e.g. `src/context.ts` or `src/retrieve.ts`
|
|
- shared parsing/model code from the layered protocol
|
|
- `src/cli/*` for follow-up CLI wiring
|
|
- docs and skill guidance
|
|
|
|
## Retrieval pipeline
|
|
|
|
1. Accept a natural-language `query`
|
|
2. Read root `.pi-map.index.md` and, when needed, root `.pi-map.md`
|
|
3. Parse paired index/map metadata through the shared format/model layer
|
|
4. Score candidate directories primarily from indexes
|
|
5. Keep the top 3 candidates by default
|
|
6. Expand strongest candidates to rich maps, likely files, and symbols
|
|
7. Emit a compact markdown bundle with stable section order and retrieval-specific title `# Context bundle: <query>`
|
|
|
|
## Candidate scoring inputs
|
|
|
|
- direct term matches in workflow hints
|
|
- direct term matches in likely files
|
|
- parent/child/sibling link context
|
|
- direct term matches in tags
|
|
- direct term matches in symbols
|
|
- path/name similarity
|
|
- root workflow routing hits
|
|
|
|
A first implementation can use deterministic weighted lexical scoring.
|
|
|
|
Candidate-selection reasoning does not need to be exposed by default.
|
|
|
|
## Parsing strategy
|
|
|
|
Reuse the paired-artifact parser/model from the layered protocol. Avoid retrieval-specific ad hoc parsing.
|
|
|
|
## Risks
|
|
|
|
| Risk | Mitigation |
|
|
|---|---|
|
|
| Retrieval becomes too fuzzy to trust | Keep output advisory and always direct agent back to source |
|
|
| Pair parser complexity grows | Extend shared format/model logic instead of command-local parsing |
|
|
| Command output becomes too large | Limit result count and keep instructions terse |
|
|
|
|
## Open choices
|
|
|
|
1. Exact scoring weights for workflow hints vs files vs tags vs symbols
|
|
2. Whether the tool should support optional structured output later
|
|
3. Whether broad architecture queries should be allowed to exceed the usual top-3 default in a later version
|
|
4. Whether later versions should support optional root-rich-map inclusion as a flag
|