forge-product-map

name	forge-product-map
description	Capture and maintain a project's product map — user journeys, scenarios, business rules, and workflow diagrams as curated Mermaid knowledge entries. Use this skill whenever someone wants to: document product flows, capture user journeys, generate scenario diagrams, maintain business rules visually, update the knowledge workspace, map user-facing routes, or bootstrap product documentation. Triggers on: /forge-product-map, capture product map, maintain user journeys, generate scenario flowcharts, document business rules, map product flows. IMPORTANT: This skill creates PRODUCT diagrams only — user journeys, UI routes, acceptance-criteria flows. It does NOT create architecture or codebase diagrams (no file paths, function names, or implementation details).
user_invocable	true
arguments	[bootstrap|refresh|gap] [projectId|scenarioName]

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.

Entry kinds and Mermaid syntax

Kind	Mermaid syntax	Description
overview	mindmap	One per project. Root = product name. Branches = major feature areas. Leaves = key user capabilities.
scenario	flowchart LR or flowchart TD	One per user journey (e.g. "Issue triage flow", "Runner pairing flow"). Nodes = user-facing steps.
workflow	stateDiagram-v2	One per entity lifecycle (e.g. "Issue status lifecycle"). States = status values; transitions = events.
rule	plain Markdown	Business rules and constraints that agents must follow. No Mermaid.

Each entry body is a Markdown document containing:

• A fenced mermaid code block (for overview/scenario/workflow)
• A brief prose paragraph before the diagram describing what it shows
• For scenario/workflow: a bullet list of backing issue ids after the diagram

Workflow

bootstrap mode

1. forge_knowledge action=list projectId=<id> — read all existing entries.
2. forge_issues action=list projectId=<id> status=released and status=closed — read shipped issues (up to 50, newest first). For each, read acceptanceCriteria + comments to extract user flows.
3. Build a map: feature area → user journeys → nodes. Apply verification gate.
4. Identify gaps (feature areas with no scenario entry, unclear workflows).
5. If gaps remain, ask the human: "I found the following gaps I can't infer from shipped issues: [list]. Can you describe [gap1]? [gap2]?" — batch all questions.
6. Write entries:
   • overview mindmap (upsert slug product-overview)
   • One scenario per identified user journey (slug: kebab of journey name, e.g. issue-triage-flow)
   • workflow stateDiagram for entity lifecycles (slug: <entity>-lifecycle)
   • rule entries for discovered business constraints
7. Set authoredBy: "agent" on all written entries.

refresh mode

1. Read existing entries (forge_knowledge action=list).
2. Read issues closed/released since last entry updatedAt (approximate: last 30 days).
3. For changed feature areas: update the relevant scenario/workflow entries.
4. Upsert only changed entries. Log which were updated vs unchanged.

gap mode

1. If scenarioName arg provided, proceed. Otherwise ask: "Which user journey should I document?"
2. Read related issues and existing entries for context.
3. Write ONE scenario entry for the named journey.
4. Apply verification gate before writing.

Output format for each entry body

<One sentence describing what this diagram shows.>

\`\`\`mermaid
<diagram code here — no click handlers, no HTML labels>
\`\`\`

**Backing evidence:**
- ISS-XXX: <AC phrase that maps to a node>
- ISS-YYY: <route or feature that maps to a node>

Out of scope (P4)

• Lifecycle hooks to auto-run at release or on a schedule — those are P4.
• Automatic trigger on issue close — manual + bootstrap-wizard only in P2.

Common mistakes to avoid

• Never add a click directive to Mermaid nodes (breaks securityLevel:strict).
• Never use HTML labels (<b>, <br/>) in Mermaid nodes (blocked by securityLevel:strict).
• Never create a node whose label is a file path, function name, or line number.
• Never overwrite a confidence:verified entry with confidence:inferred — only upgrade, never downgrade.
• If upsert returns degraded:true, log it but continue — the entry is stored (embedding will be backfilled).