Skip to main content
skill CX Codex

decision-map — Claude Code skill: planning and setup

Turn an unresolved idea into a Git-tracked decision map, then pick up the investigation in later sessions. Useful before work is ready to build.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What decision-map does

decision-map records an investigation in one Markdown file at .planning/decision-maps/<slug>.md, tracked by Git. Tickets are typed as Research, Prototype, or Grilling, with blockers and a recommended answer. Research gathers findings; Prototype tests a question with throwaway code; Grilling sharpens a decision.

The skill creates a map in one session, or resolves exactly one available ticket in a later session. It adds newly discovered questions as the frontier moves forward, rather than guessing what lies beyond it. When a decision becomes buildable work, the skill writes a linked .planning/intake/<slug>.md item. This is for discovery before a campaign; the description points to archon or fleet for work that is already scoped and sequenced.

A planning effort has one map, and a ticket with open blockers cannot be resolved. If the project has no .planning/ structure, the skill offers to set it up. The whole map is loaded into context at the start of each session, so its size matters as the investigation grows.

What it helps with

  • break an open-ended idea into research questions
  • record decisions and their reasons in a Git-tracked map
  • identify blockers before resolving a ticket
  • move buildable outcomes into .planning/intake/

Example prompts for the agent

  • Turn this idea into an investigation map with open decisions.
  • Resume the existing map and resolve one available ticket.
  • Check which tickets block this decision.

How to install decision-map

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill decision-map -a claude-code

3Manually: put the files in place

~/.claude/skills/decision-map/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/decision-map/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about decision-map

How do I install decision-map in Claude Code?

Add its marketplace with /plugin marketplace add SethGammon/Citadel, then install it with /plugin install citadel@citadel-local.

What does decision-map do?

It creates a Git-tracked map of investigation tickets and advances the work one ticket per session. Buildable outcomes become linked items in .planning/intake/.

Can decision-map resolve multiple tickets in one session?

No. A session resolves exactly one ticket, or creates the map without resolving one. Tickets remain blocked until their dependencies are resolved.

Source text

SKILL.md · MIT
---
name: decision-map
license: MIT
description: >-
  Turn a loose idea into a git-tracked, session-resumable map of typed investigation
  tickets, then drive them to resolution one at a time. The planning-loop engine for
  work that is still being figured out — too fuzzy for a campaign, too big for a
  single intake item. Resolved tickets graduate into .planning/intake/ for the
  autopilot to build.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - decision map
  - plan this out
  - figure this out
  - investigation plan
  - planning map
---

# Identity

You are the planning-loop engine. You hold *thinking* state across sessions in one
compact, git-tracked artifact — lighter than a campaign, heavier than a TODO. You
sit **below** `archon` and `fleet`: use this for the figuring-out that precedes a
campaign, when work is still being discovered rather than executed. When a ticket
resolves into buildable work, it graduates into `.planning/intake/` for `autopilot`.

## Orientation

**Use when:**
- An idea has open questions that must be resolved before it can be built.
- The work is too fuzzy for a campaign and too large for a single intake item.
- Planning needs to survive across sessions without re-deriving context each time.

**Don't use when:**
- The work is already buildable — write a `.planning/intake/` item directly.
- The work is already scoped and sequenced — run a campaign (`archon` / `fleet`).

## Protocol

### Critical constraints (do not violate)

1. **ONE MAP PER PLANNING EFFORT.** A single Markdown file at
   `.planning/decision-maps/<slug>.md`, git-tracked. It is the canonical artifact and
   is reloaded **whole** as context at the start of every session.
2. **ONE TICKET PER SESSION.** Resolve exactly one ticket, then stop. Map-building is
   its own session; do not bootstrap and resolve in the same run.
3. **FOG OF WAR.** The map is deliberately incomplete past the frontier. Do not invent
   tickets you cannot yet see. Push the frontier forward by resolving, not speculating.
4. **BLOCKING EDGES ARE REQUIRED.** Every ticket declares what blocks it. Never resolve
   a ticket whose blockers are open.

### Ticket types

- **Research** — read docs, third-party APIs, or local resources (planning notes,
  knowledge base, source). Output: findings recorded in the ticket body.
- **Prototype** — throwaway code that answers a question (a small harness for
  logic/state, or alternate UIs for look-and-feel). Keep only the **answer**, not the
  code.
- **Grilling** — a conversation that sharpens a decision. Runs the `grill` discipline.

### Mode A — Bootstrap (new map)

1. Surface the open decisions behind the idea via the `grill` discipline. Default to
   explore-and-recommend mode: resolve what the repo and docs answer yourself, and
   attach a *recommended answer* to each surfaced fork as the default to confirm
   later. Escalate to interactive one-question-at-a-time grilling only for forks the
   repo genuinely cannot resolve.
2. Write `.planning/decision-maps/<slug>.md` from the template below, with the
   frontier marked and initial tickets typed and edged. Each ticket carries its
   recommendation; leave `Resolution` empty (resolving is Mode B).
3. **Stop.** Building the map is one session's work.

### Mode B — Resume (existing map)

1. Load the whole map as context.
2. Pick one frontier ticket whose blockers are all resolved. Resolve it using the
   right type discipline (`grill` / prototype / research read).
3. Record the resolution inline in the ticket body (the decision and why).
4. Add any newly-discovered tickets with correct blocking edges. Advance the frontier.
5. If the ticket produced buildable work, write a `.planning/intake/<slug>.md` item and
   link it from the ticket.
6. **Stop.**

### Map template

```markdown
# Decision Map: {Effort Name}
Status: active | resolved
Goal: {one line — what this planning effort is trying to decide}

## Frontier
{The tickets currently resolvable. Everything past here is fog.}

## Tickets
### T1 — {title}  [Research|Prototype|Grilling]
Blocked by: {none | T#, T#}
Question: {the specific thing this ticket resolves}
Resolution: {filled in when resolved — the decision and why}
Graduated to: {.planning/intake/<slug>.md, if buildable}

### T2 — ...
```

## Quality Gates

1. Exactly one map file exists per planning effort, and it is git-tracked.
2. Exactly one ticket was resolved this session (or the map was only bootstrapped).
3. No ticket was resolved while any of its blockers were still open.
4. Every resolution records the decision *and* its reason inline.
5. Buildable outcomes were graduated to `.planning/intake/`, not left in the map.

## Fringe Cases

- **`.planning/` does not exist:** create `.planning/decision-maps/` (and
  `.planning/intake/` when graduating) on first write. If the project clearly has no
  planning convention yet, say so and offer to set it up rather than failing.
- **Map already exists at bootstrap:** do not overwrite — switch to Mode B and resume
  the existing map instead.
- **No frontier ticket is resolvable (all blockers open):** report the deadlock and
  resolve a blocking ticket first; never force-resolve past an open blocker.
- **A ticket turns out unbuildable or moot:** record why in its body and close it; do
  not graduate it to `.planning/intake/`.

## Exit Protocol

Stop after one ticket. If every ticket is resolved, set the map `Status: resolved`,
summarize the decisions, and list the intake items it graduated. Do not roll the map
into a campaign here — hand the graduated intake items to `autopilot` / `archon` /
`fleet`.

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set55

The whole set →
autopilot autopilot processes queued tickets from .planning/intake/ through automated research, implementation, and verification. CX Codex +1 ★ 937repo stars doc-gen doc-gen generates function comments, directory READMEs, and API references while following the project’s existing conventions. Use it when docs should explain code behavior rather than repeat signatures. CX Codex +1 ★ 937repo stars policy-enforcer policy-enforcer is a Claude Code subagent that checks proposed actions against Citadel’s rules and returns an allow-or-block verdict. Archon and Fleet spawn it before actions with low reversibility. CX Codex ★ 937repo stars systematic-debugging systematic-debugging stops trial-and-error edits by enforcing a four-phase root cause protocol and freezing code changes until hypotheses are tested. CX Codex +1 ★ 937repo stars archon archon — a subagent that carries a big task through phases: splits a direction into steps, hands them to other agents and keeps campaign state between runs. CX Codex ★ 937repo stars loop loop — a skill for Claude Code and Codex that runs an action repeatedly and checks the result each time, stopping when verification passes or attempts run out. Useful for fixing lint errors or test failures in an active session. CX Codex +1 ★ 937repo stars marshal The marshal skill for Claude Code parses a task, gathers context from code and project memory, and chains skills. It runs in one session and asks only if it cannot continue. CX Codex +1 ★ 937repo stars test-gen test-gen is a Claude Code skill that generates and runs unit tests matching a project's existing framework, covering happy paths, edge cases, and failures. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open