/decision-map

name: decision-map
description: 'Use when mapping unresolved architecture, policy, or scope decisions before planning, or working one decision ticket, including a prototype ticket whose throwaway evidence the prototype package builds. Also applies to "map the decisions", "decision map", and "wayfinder". Not for implementation slices of a known feature, milestone plans, general UI generation, standalone prototypes outside a decision map (use prototype), or adopting experimental code into production.'
metadata:
  version: 2.0.2
  category: development
  tags: [planning, issue-tracker, decisions, discovery, frontier, pre-planning]
  difficulty: advanced
  phase: define
  complements:
    - plan-prompts
    - task-decomposer
    - project-context-setup
    - adr-writer
    - plan-review
    - prototype

Decision Map

Scope and Trigger Boundary

Ask one discriminator before creating anything: **Do we know what should be built?** If no, map unresolved decisions. If yes, route known design into milestones with `plan-prompts` or implementation-sized work with `task-decomposer`. A decision map produces decisions and evidence, never implementation deliverables.

| Situation | Package | |---|---| | Destination or design still unclear; decisions would have to be invented | `decision-map` | | Design known; needs milestones and execution prompts | `plan-prompts` | | Feature specified; needs implementation slices, tests, risks | `task-decomposer` | | Plan exists; needs a pre-implementation audit | `plan-review` | | Plan approved; needs execution across sessions | `milestone-runner` | | Repo audit needs standalone remediation plans, optionally as issues | `codebase-advisor --issues` | | One decision needs a durable record | `adr-writer` | | Session state must survive a handoff | `handoff` |

Do not turn vague hopes into implementation tasks merely to make progress appear orderly. A sharp but currently unanswered question is a ticket. A question that cannot yet be stated sharply is fog.

Data Model

A map is one parent tracker item with five sections: `Destination`, `Notes`, `Decisions so far`, `Not yet specified`, and `Out of scope`. It is an index, not a duplicate store. A decision exists in exactly one ticket; the map holds only resolution pointers and scope boundaries.

A ticket holds one question, exactly one type, exactly one interaction mode, blockers, visible owner, session claim, and closure state. Refer to maps and tickets by linked title, never a bare identifier. Types are `decision-map:discussion`, `decision-map:research`, `decision-map:prototype`, and `decision-map:unblock`; interaction is exactly one of `decision-map:hitl` or `decision-map:afk`. On GitHub, labels are authoritative and are not duplicated in the body. Local tickets instead require the existing `Type:`, `Interaction:`, `Status:`, and `Blocked by:` headers. Read `references/ticket-types.md` before creating either backend's ticket body.

Prerequisites

Use `gh --version` and require `gh` 2.96.0 or newer only when the user explicitly selects GitHub as the tracker. Verify authentication with `gh auth status` before that path. `frontier.py` requires Python 3.12 and only the standard library. Prototype tickets require the `prototype` package to build their artifact; when it is absent, stop with `BLOCKED: install prototype` before claiming the ticket. `.docs/agents/issue-tracker.md`, when present, is the authoritative backend choice. Otherwise store maps locally in `.docs/decision-maps/<effort>/`; select GitHub only when the user expressly asks for it. Do not infer GitHub selection from a remote or authentication. Report the selected backend once and mention `project-context-setup` when the choice should be persisted. Probe GitHub capability before using native relationships. When older GitHub Enterprise or an older CLI rejects `blockedBy`, take the degraded path: generated child links in the map and `Blocked by: #N` lines in ticket bodies. The degraded index exists only to emulate absent tracker relationships.

Workflow

Mode A — Chart the Map

1. Name the destination before discussing its route. Use one concrete either-or question at a time and reuse the effort's vocabulary. 2. Sweep breadth-first for policy, architecture, scope, evidence, access, and design questions. If no fog surfaces, stop: the effort needs no decision map. 3. Ensure labels and the selected backend schema exist. Create the map with all five sections. 4. Create every question already sharp enough to ticket. Give every ticket exactly one type and interaction mode through the selected backend's labels or required local headers. 5. Wire blocker edges only after ticket creation, because the backend needs ticket identifiers before it can connect them. 6. Put the remaining unformulated uncertainty in `Not yet specified`; record conscious exclusions with a reason in `Out of scope`. 7. Compute the frontier and map state with `frontier.py`; report created topology and stop.

Charting resolves nothing, runs no research, implements nothing, and never collapses uncertainty to look tidy. Report the AFK-ready frontier separately: those tickets may be advanced by that many independent `work` invocations, each resolving at most one ticket.

Mode B — Work Through the Map

1. Load the map body and select the requested ticket or the first frontier item returned by `frontier.py`. A continuation may return to this session's already-claimed open ticket; verify that claim rather than acquiring a second one. For a newly selected `prototype` ticket, check that the `prototype` package is installed before taking ownership; if it is absent, stop with `BLOCKED: install prototype` and leave the ticket untouched (no assignment, no claim). Establish visible ownership. 2. Acquire and verify the session claim before substantive work, or re-verify the existing claim on continuation. Follow `references/claim-protocol.md`; do not infer exclusivity from assignment. A co