requirements-map

Requirements Map

Create a decision-support map for scope review before implementation. Do not inspect Git diffs, collect implementation evidence, persist approval, or modify the target repository.

Workflow

1. Read the supplied requirements in any format.
2. Normalize every requirement into the manifest below. Preserve source wording in fullText; do not invent behavior.
3. Ask for clarification when uncertainty changes scope. Otherwise record uncertainty in assumptions or openQuestions and choose the matching non-ready status.
4. Add hierarchy edges. Add cross-links only when explicit or high-confidence; set inferred: true for inferred links.
5. Save the manifest outside the target repository.
6. Run node scripts/render-requirements-map.mjs manifest.json.
7. Return the two absolute paths printed by the renderer. Do not open a browser.

The report uses the Tailwind v4 Play CDN and therefore needs internet access to compile its embedded Tailwind source in the browser. The remote script can read report content, so do not use this skill for confidential requirements. tailwind.css is also emitted as an editable copy of that exact source.

Semantic Model

Use goal → scenario → given → when → then. Represent an And clause as its inherited clause type: an And after Given is given, after When is when, and after Then is then. Keep the original And wording in fullText.

Every source requirement must appear in a node. Use statuses only from:

• ready: clear enough for scope review
• assumption: depends on a recorded assumption
• ambiguous: has more than one material interpretation
• conflict: contradicts another requirement
• missing-outcome: lacks an observable result

This readiness is about requirement clarity, not implementation completion.

Manifest Schema

The renderer accepts one strict JSON object. Unknown fields are rejected.

{
  "title": "Account recovery scope",
  "summary": "Stakeholder review of the recovery journey.",
  "nodes": [
    {
      "id": "goal-recovery",
      "type": "goal",
      "title": "Restore account access",
      "meaning": "A locked-out customer can regain access.",
      "fullText": "Customers can restore access to their account.",
      "status": "ready",
      "scenario": "recovery",
      "assumptions": [],
      "openQuestions": []
    }
  ],
  "edges": [
    {
      "source": "goal-recovery",
      "target": "scenario-email",
      "type": "contains",
      "inferred": false
    }
  ]
}

Rules:

• Root fields are exactly title, summary, nodes, and edges.
• All strings must be non-empty. IDs must match [A-Za-z0-9][A-Za-z0-9_-]{0,63} and be unique.
• nodes contains 1–50 objects with exactly the shown node fields.
• Node type is goal, scenario, given, when, or then.
• Node status uses the documented enum above.
• scenario is a stable grouping key, including for goal and scenario nodes.
• assumptions and openQuestions are arrays of non-empty strings.
• edges contains objects with exactly source, target, type, and inferred.
• Edge type is contains, precedes, or relates; inferred is Boolean.
• Edge endpoints must be different existing node IDs. Duplicate edges are rejected.
• Use contains for hierarchy, precedes for clause order, and relates only for justified cross-links.
• Include exactly one goal and at least one scenario node. Every other node must share a grouping key with exactly one scenario node.
• Connect every node to the goal through directed contains and precedes edges. relates does not establish hierarchy.
• contains supports goal-to-scenario and scenario-to-clause edges. precedes connects clauses in non-decreasing Given/When/Then order within one scenario.

Renderer

node scripts/render-requirements-map.mjs manifest.json
node scripts/render-requirements-map.mjs manifest.json --output-dir /absolute/new/directory

The optional output directory must be absolute, must not exist, and must not alias the input. By default, a unique directory is created under $TMPDIR. Publishing is atomic; failures clean up staging files.