forge-product-map

forge-product-map

Maintains a project's curated product knowledge as Mermaid visual entries. Writes overview, scenario, workflow, and rule entries via forge_knowledge action=upsert. All diagrams represent user-facing product behaviour — never internal implementation.

Modes

• bootstrap (default) — full sweep: read existing entries, read shipped issues for evidence, identify gaps, ask the human only for gaps that cannot be inferred. Write/refresh all entry kinds.
• refresh — incremental: read recently closed/released issues since the last run, update existing entries that those issues affect, add missing scenarios.
• gap [scenarioName] — produce or fill exactly ONE scenario entry. Ask the human for the scenario name if not provided.

Hard verification gate (AC5 — non-negotiable)

Before writing ANY node into a scenario or workflow diagram:

1. Every node must map to one of: a real issue id, an acceptance criterion phrase, or a user-facing route string (e.g. /projects/:slug/library).
2. NO file:line, function names, module names, or source-code identifiers as nodes. If a node names a file or function, DELETE it — replace with the user-facing action it implements.
3. Tag each entry:
   • confidence: "verified" when a shipped (closed/released) issue directly backs the node.
   • confidence: "inferred" when derived from comments, ACs, or reasonable inference.
4. Store backing issue ids in metadata.relatedIssueIds: string[].

Violating this gate produces diagrams that rot when the code changes. Product diagrams must survive a complete rewrite of the implementation.

Source priority

Read sources in this order; later sources are used only when earlier ones are insufficient:

1. Existing knowledge entries — forge_knowledge action=list (then action=get for full bodies). These are already curated; update rather than replace.
2. Shipped issues — forge_issues action=list with status=closed or status=released. Read acceptanceCriteria, description, and comments for evidence of real user flows.
3. Semantic search — forge_knowledge action=search scope=all query="<topic>" for context not in the entry list.
4. The human — ask ONLY for gaps that none of the above sources can fill. Batch all gap questions into a single message.