nelson

What this skill does

# Nelson

```!
python3 "${CLAUDE_PLUGIN_ROOT}/skills/nelson/scripts/nelson-data.py" status
```

Execute this workflow for the user's mission.

Write as Nelson's captains would write: concise, elegant, confident. Not eighteenth-century prose — the clear register of an officer who respects the reader's time. The skill's voice sets the example for the admiral's voice.

## 1. Issue Sailing Orders

- Review the user's brief for ambiguity. If the outcome, scope, or constraints are unclear, ask the user to clarify before drafting sailing orders.
- Write one sentence for `outcome`, `metric`, and `deadline`.
- Set constraints: token budget, reliability floor, compliance rules, and forbidden actions.
- Define what is out of scope.
- Define stop criteria and required handoff artifacts.

You MUST read `references/admiralty-templates/sailing-orders.md` and use the sailing-orders template when the user does not provide structure.

Example sailing orders summary:

```
Outcome: Refactor auth module to use JWT tokens
Metric: All 47 auth tests pass, no new dependencies
Deadline: This session
Constraints: Do not modify the public API surface
Out of scope: Migration script for existing sessions
```

**Establish Mission Directory:**
- **New session:** Run `nelson-data.py init` (see "Structured Data Capture" below). The script owns directory creation: it generates an 8-character hex SESSION_ID, creates `.nelson/missions/{YYYY-MM-DD_HHMMSS}_{SESSION_ID}/` with the `damage-reports/` and `turnover-briefs/` subdirectories, writes `sailing-orders.json`, `mission-log.json`, and `fleet-status.json`, writes `.nelson/.active-{SESSION_ID}` as the session marker, and prints the mission directory path to stdout. Capture that path as `{mission-dir}` for the remainder of this mission. The SESSION_ID is the segment after the last underscore in the directory name. If you need a specific SESSION_ID (e.g., testing or resuming a known id), pass `--session-id <8-hex>`.
- **Resumed session:** First, attempt auto-recovery by running `python3 .claude/skills/nelson/scripts/nelson-data.py recover --missions-dir .nelson/missions`. If this finds an active mission with handoff packets, use the structured recovery briefing to resume directly. Otherwise, if you know the SESSION_ID, read `.nelson/.active-{SESSION_ID}` to recover the mission path. Set that path as `{mission-dir}`. If you cannot determine your SESSION_ID (e.g., after a full restart), list `.nelson/missions/` and present the options to the user for selection. Set the chosen directory as `{mission-dir}`. Recover state per `references/damage-control/session-resumption.md` (prefer JSON files, fall back to quarterdeck report prose).

All mission artifacts — captain's log, quarterdeck reports, damage reports, and turnover briefs — are written inside `{mission-dir}`.

**Structured Data Capture:** Run the `nelson-data.py` script located in the skill's directory (e.g., `python3 .claude/skills/nelson/scripts/nelson-data.py init --outcome "..." --metric "..." --deadline "..."`). If installed globally, it may be in `~/.claude/skills/nelson/scripts/`. `init` creates the mission directory, the initial JSON files (`sailing-orders.json`, `mission-log.json`, `fleet-status.json` with initial phase `SAILING_ORDERS`), and the `.nelson/.active-{SESSION_ID}` marker in one atomic step. See `references/structured-data.md` for the full argument list.

**Phase Advance:** After structured data capture, advance the mission phase from SAILING_ORDERS to ESTIMATE:

```bash
python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}
```

**Session Hygiene:** Execute session hygiene per `references/damage-control/session-hygiene.md`. Skip this step when resuming an interrupted session.

**The Estimate opt-in:** Before proceeding, ask the user:

> *"Shall I carry out The Estimate before drafting the Battle Plan? I would recommend it for this mission — [brief reason]."*

Give an honest recommendation. For straightforward missions with clear scope in a single subsystem, proceed without the Estimate. For complex, ambiguous, or multi-system missions, recommend conducting it. If the user accepts, proceed to Step 2. If the user declines, record the decision and skip to Step 3:

```bash
python3 .claude/skills/nelson/scripts/nelson-data.py skip-estimate \
  --mission-dir {mission-dir} --reason "[one-line rationale]"
python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}
python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}
```

The first `advance` moves from SAILING_ORDERS to ESTIMATE. The second `advance` moves from ESTIMATE to BATTLE_PLAN; the exit validator accepts the transition because `skip-estimate` has already recorded the opt-out in `sailing-orders.json`.

## 2. Conduct The Estimate

Read `references/the-estimate.md` for the full thought process, and use `references/admiralty-templates/estimate.md` as the scaffold. Work through seven questions that turn a mission brief into a plan worth executing:

1. **Reconnaissance** — What is the terrain? What are we working with?
2. **Intent** — What are we really trying to achieve, and why?
3. **Effects** — What changes must occur to fulfil the intent?
4. **Terrain** — Where in the codebase does each effect land?
5. **Forces** — What agents, models, and context do we need?
6. **Coordination** — What depends on what? What runs in parallel?
7. **Control** — Where are the quality gates and intervention points?

**Q1 dispatches Explore sub-agents.** Send one or more Explore agents into the codebase with a scouting brief derived from the Sailing Orders; synthesise their findings into the Reconnaissance section. Q1 must follow the Explorer discipline rules in `references/the-estimate.md` (multiple focused dispatches, structured summaries, no raw file contents).

**Q2–Q3 and Q4–Q7 are delegated in two separate sub-agent dispatches** so Q2–Q7 reasoning does not consume admiral context. The first dispatch (Estimate-Drafter) produces commander's intent and effects after Q1 and before Checkpoint 2; the second dispatch (Estimate-Planner) produces terrain, forces, coordination, and control after Checkpoint 2 approves intent and effects. Both subagents inherit the admiral's model; The Estimate phase is exempt from cost-savings model selection. See `references/the-estimate.md` for the briefing contents and dispatch templates.

**Two checkpoints bracket the analytical work.** After Q1, present findings to the user and invite correction or reframing. After Q3, present intent and effects for substantive approval before planning *how*. Q4-Q7 flow from approved effects and are the admiral's professional judgement — work through them without interrupting the user. Collapse both checkpoints into a single final review only when all three conditions hold: sailing orders specify outcome, metric, and deadline; Q1 reveals no surprises; the work lands in a single subsystem. See `references/the-estimate.md` for full checkpoint discipline.

Each effect in §3 must carry **commander's guidance** (how to do it) and **acceptance criteria** (what must be true when done). Criteria flow through to captains and are verified at stand-down; captains choose the verification method per criterion (test, type-check, lint, review, visual).

Write the estimate to `{mission-dir}/estimate.md` with one H2 section per question. Split to `{mission-dir}/estimate/0N-name.md` only when a section grows unwieldy.

**Phase Advance:** After the user approves the final estimate, advance from ESTIMATE to BATTLE_PLAN:

```bash
python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}
```

## 3. Draft Battle Plan

When The Estimate has been conducted, the Battle Plan inherits the analytical work: terrain, forces, coordination, and control are already decided. The Battle Plan step is operational — it turns approved effects into task assignments. When the Esti