chart-map

Files (5)

• SKILL.md
• data-contracts.md · references/
• github_map_ops.py · scripts/
• local_map_ops.py · scripts/
• map_core.py · scripts/

SKILL.md (first lines)

# chart-map

Chart the way; don't charge at the goal. The output is a **Decision map** — one
item indexing the whole effort — plus child **Decision tickets**: questions whose
resolution is a *decision*, each sized to one session.

**Plan, don't do.** Charting creates the map and hand-resolves nothing (ADR
0041). One charting run is one session, and it ends at Step 5.

Emit this diagram once, at the start, so the user can see the whole run:

```
CHART A DECISION MAP — one session, then stop
─────────────────────────────────────────────

  ① PREFLIGHT — ask which backend
  │   local docs/decision-map/<slug>/
  │   or GitHub issues + sub-issues
  │   name it BEFORE any charting
  ▼
  ② DESTINATION  (HITL — the human answers)
  │   what does arriving look like?
  │   one or two sentences, one line, first
  ▼
  ③ FRONTIER — breadth-first, never deep
  │   HITL too: you ask, the human answers
  │   can you STATE the question now?
  │     yes → ticket · no → fog
  │     past the destination → out of scope
  │
  │   no fog anywhere? ■ STOP — no map
  │      needed; hand to grill-then-plan
  ▼
  ④ GATE — dry run first, always
  │   create · skip (exists) · merge
  │   show every label → get a yes → --real
  ▼
  ⑤ RESEARCH subagents, in parallel
  │   findings posted back with `resolve`
  ▼
  ⑥ LINT — run the check, report it
  │   exit 0 clean · exit 3 findings
  ▼
  ■ STOP — report the `frontier`, hand off
     charting hand-resolves nothing
```

## Step 0 — Preflight: name the backend before you chart

**Two backends exist. Ask which one, before anything else happens** — even if
the user never mentioned a tracker. Someone who expected their map on a shared
board needs to learn where it lands **here**, not after spending a session
charting.

| backend | where the map lives | how it is shared | needs |
|---|---|---|---|
| **local markdown** (default) | `docs/decision-map/<slug>/` in this repo | by committing the repo | nothing |
| **GitHub Issues** | an issue per map, a **sub-issue** per ticket, native `blocked-by` dependencies — plus a **Map pointer** at `docs/decision-map/<slug>/map.md` so the repo lists the map (ADR 0173) | the repo's issue tracker — visible to anyone with access | `gh auth status` passing, and a repo you may write issues to |

Default to **local** and say so; only use GitHub if the user asks for a board or
names a repo. Azure DevOps is **not** available (ADR 0059 — its half of the
marker probe has never been run). If ADO specifically is a hard requirement,
stop and say decision-map cannot do that yet.

Do **not** offer to install `ado-backlog` or `github-backlog` in either case —
neither plugin can drive a decision map, so offering them would be a false
promise. `github-backlog` in particular is a *findings-to-issues* pipeline, not
a decision map; the two write different things to the same tracker.

Then fix these two, and use them for every command from Step 1 down:

| | local | GitHub |
|---|---|---|
| **`<ops>`** | `${CLAUDE_SKILL_DIR}/scripts/local_map_ops.py` | `${CLAUDE_SKILL_DIR}/scripts/github_map_ops.py` |
| **extra flag on every call** | *none* — `--root` defaults to `docs/decision-map` | **`--repo <owner>/<repo>`, always.** It is never inferred from the git remote: this writes issues; `--root` only if the pointer must land somewhere other than `docs/decision-map` |

Run `<ops>` with `python`, from the repo root, so a local map lands at its
ADR-0042 default location. Everything from Step 1 down is backend-neutral — the
subcommands, the flags, the JSON shapes and the gate are identical on both
(ADR 0062); only `<ops>` and that one flag change.

**On GitHub, two limits are hard and worth knowing before you grill breadth-first:**
a map cannot exceed **100 tickets** (GitHub's sub-issue ceiling) and a ticket
cannot be blocked by more than **50** others. `chart` checks both before it
writes anything rather than failing partway.

**Contract** — every subcommand, flag and JSON shape used below is fixed by
`references/data-contracts.md`. Where this skill and the
contract disagree, the contract wins.

The map is repo docs, so it is committed through **assisted git** — offer the
commit, never make it automatically.

## Step 1 — Name the destination

Run a short grilling exchange (load `sp-grill-with-doc` the way your harness loads
skills, if it is available; otherwise ask directly, one question at a time):
**what does reaching the end look like?** A written spec, a locked decision, a
change made in place?

One or two sentences. The destination is what every ticket is measured against,
and what makes "out of scope" decidable. Write it down before any ticket exists.

It is stored as a **single line** — the tool collapses any line break to a
space, in `title` and `destination` alike, so that a stray newline can
never truncate the value or inject a heading into the map document. Write it as prose,
not as a bulleted list or a paragraph break. (`notes` is different: it is a
**list** region now, one bullet per entry, and each bullet is flattened the
same way — ADR 0101.)

### The HITL guard — it governs this step and Step 2 both

Naming the destination is itself a HITL grilling exchange, and so is the
breadth-first grill that follows. **An agent that answers its own grilling
questions has broken the type.** A map charted that way is fiction: every
ticket on it is measured against a destination the human never actually agreed
to, and the whole effort then runs off it.

The line is *who supplies the answer*, not who does the work:

From ThodsaphonSonthiphin/workflow-daily-work, MIT.

More from ThodsaphonSonthiphin/workflow-daily-work