Deep

---
name: deep
description: Discovery, planning, and implementation pipeline. Modes — intent: capture the problem; discovery: system audit → phase specs; plan: implementation blueprint; implement: execute sections; auto: autonomous end-to-end from a phase list; goalloop: loop toward a stated end state, carving increments as it goes, until every acceptance line is evidenced. Accepts @path, inline text, or no argument.
license: MIT
compatibility: Requires uv (Python 3.11+). Optional Gemini or OpenAI API key for external review.
---

# Deep Skill

Pick mode by question:

| Question | Mode | Output | Load-bearing step |
|---|---|---|---|
| "Here's a problem we have" | `intent` | `intent.md` | **Grilling** (is the problem real?) |
| "What should we build?" | `discovery` | audit + phase specs | **Topic enumeration** |
| "How do I build phase X?" | `plan` | blueprint + sections | **Interview** (Premise Challenge) |
| "Code section X" | `implement` | tested code | **Confidence gate** |
| "Do it all autonomously" | `auto` | multi-phase plan + implement chain | **Discovery bridge** |
| "Get me to this end state" | `goalloop` | goal + increment ledger, looped | **Three-clause done test** |

```
/deep intent "the price board lags the rack"         → intent.md
/deep discovery @path [--depth=quick|standard|deep]  → audit + phase specs
/deep plan @spec.md [--from-prd @prd.md | --from-adr @adrs/ | --from-intent @intent.md]  → blueprint
/deep implement [@dir] [--auto]                      → execute sections
/deep auto @phases/                                  → end-to-end
/deep goalloop [@target] [--goal "<end state>"] [--acceptance "<observable>"] [--max-iters N]
```

**Discovery depth** (`audit` only):
- `quick`: scan + topics + interview + docs + phasing only (5-10 min)
- `standard` (default): all steps
- `deep`: all steps + cross-verify pass on top findings

**Express paths** (`plan` only): when input is already structured, skip research + interview.
- `--from-prd @prd.md`: PRD with requirements + acceptance criteria
- `--from-adr @adrs/`: existing ADR file or directory of ADRs
- `--from-intent @intent.md`: an **accepted** intent. Trace every spec
  requirement back to a line in it; anything you cannot trace is scope you are
  adding, so say so rather than smuggling it in.

Also accepts inline text or no argument — see **Resolve Input**.

---

## First Actions

### 1. Validate environment
```bash
bash ${DEEP_PLUGIN_ROOT}/scripts/checks/validate-env.sh
```
Parse JSON. Map `review_available` to `review_mode` (`full`/`gemini_only`/`openai_only` → `external_llm`; `none` → ask user: opus/sonnet/skip/exit). If `valid == false`: stop.

### 2. Vault init + routing
Lifecycle concerns live in `references/integration-protocol.md`:
- §1 vault resolution (sets `vault_available`)
- §2 skill-router invocation between phases
- §3 architecture-audit prompt (plan + implement)
- §4 end-of-mode vault-curator

### 3. Resolve input

| Argument | Mode |
|---|---|
| `discovery @path` or `@dir` without `claude-plan.md` | `audit` |
| `plan @file.md` or `@file.md` | `plan` |
| `implement [@path]` or `@dir` with `claude-plan.md` + `sections/` | `implement` |
| `auto @path` | `auto` |
| `goalloop [@target]`, flags optional | `goalloop` |
| Inline text (no `@`) | Synthesize via `references/auto-spec-synthesis.md` |
| Empty | Ask: `"What do you want to build or audit?"` |

`--no-reframe`: skip Premise Challenge in interview. Auto always skips. Plan skips when spec has >5 concrete file paths or function signatures.

### 4. Setup session

For `audit` / `plan` / `auto`:
```bash
uv run ${DEEP_PLUGIN_ROOT}/scripts/checks/setup-session.py \
  --file "<target>" --plugin-root "${DEEP_PLUGIN_ROOT}" \
  --review-mode "${review_mode}" --session-id "${DEEP_SESSION_ID}" \
  --workflow "<audit | plan | auto | goalloop>" \
  [--depth "<quick|standard|deep>"] \
  [--from-prd "<path>" | --from-adr "<path>"]
```
`--depth` is `audit`-only. `--from-prd` / `--from-adr` are `plan`-only and mutually exclusive.
`--goal` / `--goal-file`, `--acceptance` (repeatable, at least one) and `--max-iters` are `goalloop`-only.
Parse JSON: `new` → proceed; `resume` → continue at ready step; `complete` → stop; `success == false` → error.

For `implement`: skip setup-session. Use `@path` (or its parent), else `~/.claude/.deep-plan-active`. Validate `claude-plan.md`, `sections/index.md`, `.deepstate/state.json` exist.

---

## Workflow Loop

```
1. tracker.ready() → next unblocked step
2. Auto mode, human-interactive step (user-review,
   context-check-pre-review, context-check-pre-split):
   run auto-gate.py check.
     exit 0 → close with its close_reason, repeat
     exit 1 → do NOT close. Report the failing sections
              and stop this phase.
3. Read step's reference file (index below)
4. Execute step
5. tracker.close(issue_id, reason)
6. Auto mode: if step was output-summary (phase complete),
   run implement for that phase before next phase
7. Repeat until all closed
```

**Advance on green, halt otherwise.** Step 2 used to close every checkpoint with
"Auto mode: skipped" regardless of what had happened, so a run continued past
phases it should have stopped at. It now consults recorded verification status:

```bash
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/auto-gate.py \
  --planning-dir "${planning_dir}" check --expected-sections <N>
```

A section that never recorded a result counts as `human_needed`, not as passing.
Absence of evidence is the usual way an autonomous run convinces itself
everything is fine.

---

## Reference Index

### Cross-cutting
| Concern | File |
|---|---|
| Intent capture (`/deep intent`) | `references/intent-capture.md` |
| Secondary repository freshness | `references/repository-freshness.md` |
| Guardrails + test lock | `references/guardrails.md` |
| Target-repo CLAUDE.md | `references/claude-md-protocol.md` |
| Policy at spec time | `references/spec-policy.md` |
| Vault, routing, architecture-audit, vault-curator | `references/integration-protocol.md` |
| Discovery findings reuse for auto + plan | `references/discovery-bridge.md` |
| Plan mutation (split/skip/reorder/insert/amend) | `references/plan-mutation-protocol.md` |
| Resume after compaction | `references/resume.md` |
| Which questions to ask (information gain) | `references/question-selection.md` |

### Discovery (`--workflow audit`)
| Step | Reference |
|---|---|
| Quick Scan, Deep Research | `references/audit-research-protocol.md` |
| Empirical Data | `references/audit-data-collection.md` |
| Topic Enumeration *(load-bearing)* | `references/audit-topic-enumeration.md` |
| Coverage Validation | `references/audit-coverage-validation.md` |
| Stakeholder Interview | `references/audit-interview-protocol.md` |
| Audit Docs | `references/audit-doc-writing.md` |
| Build-vs-Buy | `references/audit-build-vs-buy.md` |
| Phase Specs | `references/audit-phasing.md` |
| External Review | `references/external-review.md` |

### Plan (`--workflow plan`)
| Step | Reference |
|---|---|
| Research | `references/research-protocol.md` |
| Interview *(load-bearing)* | `references/interview-protocol.md` |
| Write Spec, Generate Plan | `references/plan-writing.md` |
| Context Check | `references/context-check.md` |
| External Review | `references/external-review.md` |
| Apply TDD | `references/tdd-approach.md` |
| Section Index, Sections | `references/section-index.md`, `references/section-splitting.md` |

Generate sections step:
```bash
uv run ${DEEP_PLUGIN_ROOT}/scripts/checks/generate-sections.py \
  --planning-dir "${planning_dir}" --session-id "${DEEP_SESSION_ID}"
```

**Coverage gate** (run after sections are written, before `output-summary` closes):
```bash
uv run ${DEEP_PLUGIN_ROOT}/scripts/checks/check-coverage.py \
  --planning-dir "${planning_dir}"
```
Exit 0 = pass, exit 1 = missing items (do NOT close output-summary). Parse JSON `missing` list; either add sections, mark items deferred in spec, or escalate to user.

### Intent (`/deep intent`)
Standalone entry point, not a step in `plan`. `/deep plan @spec.md` is unchanged.
Full protocol in `references/intent-capture.md`.

Record the problem in the originator's words — do **not** translate it into
engineering terms, that is `plan`'s job. Ask at most 6 questions, none that the
codebase can answer. Then grill the draft with `Skill(grilling)` to test whether
the problem is real, owned and measurable, and offer documents as grist when the
user has them.

```bash
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/intent.py new --title "..." --out "${planning_dir}/intent"
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/intent.py validate <path>     # exit 1 = errors
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/intent.py decide <path> --status accepted --by "<who>" --reason "..."
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/intent.py publish <path> --repo "${target_root}" --commit
```

Rules that are not negotiable:
- `decide --by` must be a real answer from the user, never your inference.
- **Auto mode leaves `status: draft` and `source: agent`.** It never writes
  `accepted`, and it says so in the summary.
- `publish` writes into the user's repo, so confirm first. Without it the intent
  stays in the session directory.

### Auto (`--workflow auto`)
Multi-phase: parses `phasing-overview.md`, plans each phase in topological order, implements before next dependent phase plans. First phase = full plan workflow; later phases use `references/discovery-bridge.md`. Human-interactive steps auto-close at ready time (do NOT pre-close — breaks dependency chain).

Example: `plan P01 → implement P01 → plan P03 → implement P03 → plan P05 → implement P05`

### Goalloop (`--workflow goalloop`)
Starts from an end state, not from phases someone already enumerated. Full
protocol in `references/goalloop-protocol.md`; all seven control steps point
at it. Per iteration: `begin` → increment as an intent → nested `plan` session
under `iterations/iNN/` → `implement` → `evidence` → `end` → `tick`.

**Every flag is optional.** With no `--goal` or `--acceptance`, elicit them
per §0 — restate any goal already described rather than re-asking it, and use
`AskUserQuestion` (`multiSelect`) to turn the end state into acceptance lines
the user ticks. Ask; never invent, never refuse the invocation. Check the
draft before setting it, and show a flagged line to the user rather than
quietly rewriting it into something measurable:

```bash
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/goalloop.py check-goal \
  --goal "<statement>" --acceptance "<line>"   # no session needed; 1 = unusable
```

```bash
GL="python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/goalloop.py --planning-dir ${planning_dir}"
${GL} tick   # 3 = iterate · 0 = goal met · 1 = stop, needs a human · 2 = usage
```

`tick` decides, not you: it reads recorded artifacts and needs all three
clauses — ledger clear, gates green, every acceptance line evidenced. New
information is triaged explicitly (`--kind blocker` preempts, `deferrable`
splices), never inferred. Exit 1 on a blocked increment is a debt, not an end:
when the person says the blocker is cleared, `${GL} unblock --increment <id>
--because "<what cleared it>"` returns it to the queue and `tick` reads
`running` again — never unblock work the loop itself could have cleared.
Intents stay `draft`/`agent`, publishing is confirm-first, and clarification
rounds run at `--budget 2`.

### Implement
All section-level discipline lives in `references/implement-protocol.md`:
- Phase 1: confidence gate (1-10 rating) *(load-bearing)*
- Phase 2-3: read spec + standards, tests first
- Phase 4: eval check (capability + regression)
- Phase 5-6: review + quality gate (ruff + mypy + bandit + pytest --cov)
- Phase 7: context chaining (`section_outcome` → `impl-progress.md`)
- Phase 9: rollback (3-strike rule)
- Phase 10: post-mortem — answer "what would have prevented the rework?". Architectural answer → suggest `Skill(codebase-design)`. Spec-clarity answer → log under `## Spec gaps observed`. None → say so. Stop hook enforces.

Reads from `.deepstate/state.json`.

Whenever discovery, planning, research, or implementation review consults a
different project—whether a local checkout or a newly cloned repository—load
`references/repository-freshness.md` first. Refresh the secondary project's
remote default branch, normally `origin/main`, immediately before using it;
never rely on a stale local `main`. Preserve both repositories' working trees,
record the fetched commit, and explicitly report fetch failures or missing
remotes as freshness limitations.

**Record every section's outcome after Phase 6**, in both interactive and auto
mode. This is what `/deep auto` routes on, and an unrecorded section counts as
`human_needed`:

```bash
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/auto-gate.py \
  --planning-dir "${planning_dir}" record \
  --section "<section>" --gates-passed <true|false> \
  [--blocking-findings N] [--strikes N] [--detail "..."]
```

A non-passing section is added to the needs-human queue automatically.

#### `--auto` (implement only)

Runs every section without stopping to ask, without the multi-phase chain that
`/deep auto` adds. Use it when the blueprint is solid and you intend to review
the whole result at the end.

It changes three behaviours, all already specified in
`references/implement-protocol.md`:

| Phase | Interactive | `--auto` |
|---|---|---|
| 1, confidence 1-4 | `Skill(grilling)` to resolve, then re-rate | Log, SKIP or SPLIT, record `low_confidence`, next section |
| 5a, review context | Ask provide / skip / auto-discover | Straight to auto-discover |
| 9, three strikes | Ask the user | Roll back, record `three_strikes`, next section |

**It skips sections; it does not skip reporting them.** Every skip lands in the
needs-human queue, and the run summary must end with:

```bash
python3 ${DEEP_PLUGIN_ROOT}/scripts/checks/auto-gate.py \
  --planning-dir "${planning_dir}" handoff
```

Append that output to `impl-summary.md`. A `--auto` run that reports success
while silently holding skipped sections is the failure mode this exists to
prevent.

A `PreToolUse` hook blocks credential writes and pauses on paths the target repo
declared protected. It needs no invocation. When it fires, the message names the
rule and the config file — fix the cause, do not reach for `DEEP_GUARD=off`. See
`references/guardrails.md`.

---

## Guardrails

1. **Always read the reference file for the current step before executing.**
2. **Never skip a step — `tracker.ready()` determines order.**
3. **Always close the step with `tracker.close()` after completing it.**
4. **Implement mode:** Do not exit until `impl-summary.md` exists (Stop hook enforces).