maestro-flow-one 0.1.0

package/claude/maestro-flow/commands/learn/second-opinion.md

@@ -0,0 +1,167 @@
+---
+name: learn-second-opinion
+description: Multi-perspective analysis with review, challenge, and consult modes
+argument-hint: "<target> [--mode review|challenge|consult]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Structured second-opinion workflow for code, decisions, or plans. Three modes inspired by gstack `/codex`:
+
+- **review** (default): 3 parallel agents with distinct personas (pragmatist, purist, strategist) independently assess the target
+- **challenge**: single adversarial agent that tries to break the approach, find hidden assumptions, and propose alternatives
+- **consult**: interactive Q&A mode where the agent studies the target and answers your questions
+
+Decoupled from the phase/execution lifecycle — can be invoked on any piece of code or knowledge at any time. Findings persist to `lessons.jsonl`.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Target resolution (auto-detected):**
+- File path → analyze that file's content
+- Wiki ID (`<type>-<slug>`) → fetch via `maestro wiki get`
+- `HEAD` or `staged` → analyze current git diff (`git diff HEAD` or `git diff --staged`)
+- Phase number (e.g., `3`) → resolve via `state.json.artifacts[]` to find plan in scratch dir
+
+**Flags:**
+- `--mode review` — 3-persona parallel review (default)
+- `--mode challenge` — Adversarial single-agent analysis
+- `--mode consult` — Interactive Q&A session
+
+**Storage written:**
+- `.workflow/learning/opinion-{slug}-{YYYY-MM-DD}.md` — Opinion report
+- `.workflow/learning/lessons.jsonl` — New insights from analysis (source: "second-opinion")
+- `.workflow/learning/learning-index.json` — Updated index
+
+**Storage read:**
+- Target content (file, wiki entry, diff, or plan)
+- `.workflow/specs/` — Project conventions for context
+- `maestro wiki search` — Related knowledge entries
+- `.workflow/learning/lessons.jsonl` — Prior insights about the topic
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target
+- File path: Read the file
+- Wiki ID: `maestro wiki get <id>`
+- `HEAD`: `git diff HEAD` (unstaged + staged changes)
+- `staged`: `git diff --staged`
+- Phase N: Resolve via `state.json.artifacts.find(a => a.type === 'plan' && a.phase === N)` → read `.workflow/{artifact.path}/plan.json`
+- If unresolvable, AskUserQuestion for clarification
+
+### Stage 2: Load Context
+- Read relevant specs: `Skill({ skill: "maestro-flow", args: "--cmd spec-load" })` silently to get project conventions
+- Search wiki: `maestro wiki search "<target topic>"` for related entries (top 5)
+- Search lessons: grep `lessons.jsonl` for entries related to the target area
+- Build context brief: target content + conventions + related knowledge
+
+### Stage 3: Execute Mode
+
+#### Mode: review (default)
+Spawn 3 Agents in a single message with distinct personas:
+
+**Agent 1 — Pragmatist:**
+- Focus: simplicity, YAGNI, maintenance cost, readability
+- Question: "Is this the simplest thing that could work? What's the maintenance burden?"
+- Evaluates: complexity score, abstraction depth, dependency count
+
+**Agent 2 — Purist:**
+- Focus: correctness, type safety, edge cases, error handling
+- Question: "What assumptions can be violated? Where are the edge cases?"
+- Evaluates: error paths covered, type completeness, invariant preservation
+
+**Agent 3 — Strategist:**
+- Focus: scalability, extensibility, architecture alignment
+- Question: "Does this support future growth? Does it fit the overall architecture?"
+- Evaluates: coupling, cohesion, architecture constraint compliance
+
+Each agent returns:
+```json
+{
+  "persona": "pragmatist|purist|strategist",
+  "verdict": "approve|concern|reject",
+  "confidence": "high|medium|low",
+  "findings": [{ "severity": "high|medium|low", "description": "...", "location": "file:line", "suggestion": "..." }],
+  "summary": "one paragraph assessment"
+}
+```
+
+#### Mode: challenge
+Spawn 1 Agent as an adversarial reviewer:
+
+- Try to find the weakest assumption in the approach
+- Propose a concrete scenario that breaks the current implementation
+- Identify the single biggest risk
+- Suggest an alternative approach and argue why it might be better
+- Apply forcing questions:
+  - "What assumption would invalidate this entire approach?"
+  - "What's the simplest thing that breaks this?"
+  - "If you had to rewrite this in 6 months, what would you regret?"
+  - "What's the implicit contract that isn't enforced?"
+
+#### Mode: consult
+Interactive loop:
+1. Agent studies the target content thoroughly
+2. Display: "Target loaded. What would you like to know?"
+3. AskUserQuestion for the first question
+4. Agent answers with code references and evidence
+5. Loop: AskUserQuestion for follow-up or "done" to exit
+6. On exit, compile all Q&A into the report
+
+### Stage 4: Synthesize
+Across all perspectives (or from single agent in challenge/consult):
+- **Points of agreement**: findings all personas share
+- **Points of disagreement**: where personas diverge (with reasoning)
+- **Verdict**: combined assessment with confidence level
+- **Top 3 recommendations**: prioritized by impact
+
+### Stage 5: Persist & Report
+1. Write `.workflow/learning/opinion-{slug}-{date}.md`:
+   - Target summary
+   - Per-persona findings (review) / adversarial analysis (challenge) / Q&A transcript (consult)
+   - Synthesis: agreements, disagreements, verdict
+   - Recommendations
+2. Append non-trivial findings to `lessons.jsonl`:
+   - `source: "second-opinion"`, `category: "pattern"` or `"antipattern"` or `"decision"`
+   - Tags: `["second-opinion", "{mode}", "{target-slug}"]`
+3. Update `learning-index.json`
+4. Display summary with verdict and recommendations
+
+**Next-step routing:**
+- Create issue for a finding → `/manage-issue create <description>`
+- Decompose patterns found → `/learn-decompose <path>`
+- Follow-along on the code → `/learn-follow <path>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable (file/wiki/diff/plan not found) | Verify target argument, provide correct path or ID |
+| E002 | error | Unknown --mode value | Use: review, challenge, or consult |
+| W001 | warning | One review agent failed — partial perspectives | Proceed with available agents, note incomplete coverage |
+| W002 | warning | No related wiki entries found for context | Proceed without wiki context |
+| W003 | warning | Git diff empty (no changes) for HEAD/staged target | Nothing to review; suggest using a file path instead |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved and content loaded
+- [ ] Context gathered (specs, wiki, lessons)
+- [ ] Mode executed correctly:
+  - review: 3 agents spawned in parallel, all returned findings
+  - challenge: adversarial analysis completed with forcing questions
+  - consult: interactive Q&A loop completed
+- [ ] Synthesis produced with agreements, disagreements, verdict
+- [ ] Report written to `opinion-{slug}-{date}.md`
+- [ ] Non-trivial findings appended to `lessons.jsonl`
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/`
+- [ ] Summary displayed with verdict and next-step routing
+</success_criteria>

package/claude/maestro-flow/commands/lifecycle/amend.md

@@ -0,0 +1,300 @@
+---
+name: maestro-amend
+description: Collect deficiency signals from workflow artifacts, sessions, and user reports, then generate overlays to amend workflow commands
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Signal-driven overlay generator — collects workflow deficiency signals from heterogeneous sources (verification gaps, review findings, debug sessions, open issues, user feedback), diagnoses which commands need amendment, and batch-generates targeted overlays to fix them.
+
+Differs from `/maestro-overlay` which takes a single explicit intent. This command **discovers** what needs amending by analyzing workflow artifacts, then proposes and applies overlay fixes automatically.
+
+**Mechanism**: All amendments use the overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+$ARGUMENTS — optional description and/or source flags.
+
+### Signal Sources
+
+| Flag | Source | What it collects |
+|------|--------|------------------|
+| `--from-verify <dir>` | `verification.json` | Workflow gaps exposed by verify failures |
+| `--from-review <dir>` | `review.json` | Process deficiencies from code review |
+| `--from-session <id>` | Session artifacts | Problems encountered during workflow execution |
+| `--from-issues ISS-xxx,...` | `issues.jsonl` | Issues that trace to command deficiency |
+| `--scan` | Auto-scan `.workflow/` | Discover all workflow-related signals |
+| _(positional text)_ | User description | Direct observation of command deficiency |
+
+Multiple sources combinable. No flags and no description → interactive mode.
+
+### Control Flags
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Generate overlay JSON, show preview, don't install |
+| `-y` | Skip confirmations |
+
+### Signal-to-Overlay Classification
+
+A signal becomes an overlay candidate when it identifies a **workflow command deficiency** — a missing step, missing precondition, absent reading, or gap in success criteria. Signals about code bugs (not command gaps) are out of scope; suggest `/maestro-quick` or `/maestro-plan --gaps` for those.
+
+### CLI Targeting
+
+Overlays support the `cli` field to target different workflow systems:
+- `"cli": "claude"` (default) → patches `.claude/commands/{name}.md`
+- `"cli": "codex"` → patches `.codex/skills/{name}/SKILL.md`
+- `"cli": "both"` → patches both paths
+
+When diagnosing signals, determine which CLI's workflow is affected and set the `cli` field accordingly.
+
+### Output
+- Overlay files: `~/.maestro/overlays/amend-{slug}.json`
+- Optional docs: `~/.maestro/overlays/docs/amend-{slug}.md`
+</context>
+
+<execution>
+### 1. Collect signals
+
+Parse $ARGUMENTS for source flags and description text.
+
+**If no sources and no description** → interactive mode:
+Scan `.workflow/` for recent artifacts containing workflow-level signals:
+
+```
+candidates = []
+
+# Verification: workflow gaps (not code bugs)
+for each verification.json in .workflow/scratch/*-verify-*/
+  extract must_have_failures, anti_pattern items
+  filter for items whose fix_direction points at a command gap
+  (e.g., "missing pre-check step", "no reading for X", "success criteria incomplete")
+
+# Review: process findings
+for each review.json in .workflow/scratch/*-review-*/
+  extract findings tagged as "process" or "workflow"
+
+# Debug sessions: root causes tracing to command omission
+for each understanding.md in .workflow/scratch/*-debug-*/
+  extract root causes where cause_type mentions workflow/command
+
+# Open issues: workflow-tagged
+issues = read .workflow/issues/issues.jsonl
+  | filter status == "open" AND tags include "workflow" or "command"
+
+# Execution summaries: deviations
+for each summary in .workflow/scratch/*-plan-*/.summaries/
+  extract plan deviations that suggest a missing command step
+```
+
+Display scan results and use AskUserQuestion (multiSelect) to let user pick sources. Also allow user to add a freeform description.
+
+**If source flags** → extract signals from each specified source.
+
+**If only description** → user's text is the sole signal. Parse for:
+- Which command(s) are affected
+- What's missing or broken in the command flow
+- What the expected behavior should be
+
+### 2. Diagnose: map signals to command patches
+
+For each signal, determine:
+
+```
+{
+  signal_id: "SIG-001",
+  source: "verify:scratch/20260426-verify-M1/",
+  description: "maestro-execute skipped pre-flight when no test suite exists",
+  target_command: "maestro-execute",
+  target_section: "execution",
+  patch_mode: "append",
+  fix_direction: "Add fallback verification when no test suite detected",
+  severity: "medium"
+}
+```
+
+**Diagnosis heuristics:**
+
+| Signal pattern | Target section | Mode |
+|---------------|----------------|------|
+| Missing pre-check / gate | `execution` | `prepend` |
+| Missing post-step / verification | `execution` | `append` |
+| Missing reading / context | `required_reading` or `deferred_reading` | `append` |
+| Incomplete success criteria | `success_criteria` | `append` |
+| Missing error handling | `error_codes` | `append` |
+| Scope/context gap | `context` | `append` |
+| Entirely new concern | _(new section)_ | `new-section` |
+
+If target command is ambiguous, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred) or `~/.claude/commands/<name>.md` to confirm the right section.
+
+### 3. Group and plan overlays
+
+Group signals by target command. Signals hitting the same command **and** same section merge into one patch. Different sections on the same command stay as separate patches in one overlay.
+
+Decide overlay granularity:
+- **Single-concern** (1–2 signals on same command) → one overlay per command: `patch-{command}-{slug}.json`
+- **Multi-concern** (3+ signals across commands) → one umbrella overlay: `amend-{slug}.json`
+
+For each planned overlay, read the target command's pristine source to:
+- Verify the section exists
+- Check for existing overlays (via `<!-- maestro-overlay:` markers)
+- Confirm the injection point makes sense
+
+### 4. Preview injection points
+
+For each target command, render a section map with injection points (same format as `/maestro-overlay`):
+
+```
+=== maestro-execute.md (1 existing overlay) ===
+
+  <purpose>
+  <required_reading>
+     ├─ [existing] require-spec-before-plan #0
+  <context>
+  <execution>
+     ├─ [existing] require-spec-before-plan #1  "Pre-check: Load Spec"
+     ├─ [existing] cli-verify-after-execute #0  "CLI Verification"
+     >>> NEW: prepend — SIG-001 "Fallback verify when no tests"
+     >>> NEW: append  — SIG-003 "Issue sync retry on failure"
+  <error_codes>
+  <success_criteria>
+     >>> NEW: append  — SIG-002 "Verify issue status updated"
+
+=== maestro-plan.md (0 existing overlays) ===
+
+  <purpose>
+  <required_reading>
+  <context>
+     >>> NEW: append  — SIG-004 "Load prior patch history"
+  <execution>
+  <success_criteria>
+```
+
+Use AskUserQuestion to confirm:
+- **"Apply all"** — proceed with all patches
+- **"Select patches"** — per-signal confirmation
+- **"Edit"** — modify a specific signal's target/section before proceeding
+- **"Cancel"** — abort
+
+### 5. Draft overlay JSON
+
+For each overlay, build the JSON following the overlay schema:
+
+```json
+{
+  "name": "amend-execute-verify-fallback",
+  "description": "Add fallback verification and issue sync retry to maestro-execute [from: AMEND-20260426]",
+  "targets": ["maestro-execute"],
+  "cli": "claude",
+  "priority": 60,
+  "enabled": true,
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "prepend",
+      "content": "## Fallback Verification (patch: SIG-001)\n\nIf no test suite exists for the affected module, run a structural verification instead:\n..."
+    },
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## Issue Sync Retry (patch: SIG-003)\n\nIf issue status sync fails, retry once before logging as warning:\n..."
+    },
+    {
+      "section": "success_criteria",
+      "mode": "append",
+      "content": "- [ ] Issue statuses confirmed synced after execution (patch: SIG-002)"
+    }
+  ]
+}
+```
+
+**Content rules:**
+- Heading includes `(patch: SIG-NNN)` for traceability
+- Content is concise — fix the gap, nothing more
+- `@~/.maestro/overlays/docs/` references for anything longer than 10 lines
+- If supplementary doc needed, write it to `~/.maestro/overlays/docs/amend-{slug}.md` first
+
+Write overlay JSON to `~/.maestro/overlays/amend-{slug}.json`.
+
+If `--dry-run`, show the JSON and section map preview, then stop.
+
+### 6. Install overlays
+
+For each generated overlay:
+
+```bash
+maestro overlay add ~/.maestro/overlays/amend-{slug}.json
+```
+
+On validation failure, fix the JSON and retry (max 2 attempts).
+
+### 7. Report
+
+```
+=== AMEND OVERLAYS INSTALLED ===
+Session:   AMEND-20260426
+Signals:   5 collected, 4 applied, 1 skipped (code bug, not command gap)
+Overlays:  2 created
+
+  amend-execute-verify-fallback
+    Targets:  maestro-execute (3 patches: exec prepend, exec append, criteria append)
+    Path:     ~/.maestro/overlays/amend-execute-verify-fallback.json
+    Source:   SIG-001, SIG-002, SIG-003
+
+  amend-plan-context-history
+    Targets:  maestro-plan (1 patch: context append)
+    Path:     ~/.maestro/overlays/amend-plan-context-history.json
+    Source:   SIG-004
+
+Skipped:
+  SIG-005   "Missing null check in auth.ts" → code bug, use /maestro-quick
+
+Re-apply:  maestro overlay apply
+Remove:    maestro overlay remove amend-execute-verify-fallback
+Inspect:   maestro overlay list
+```
+
+### Post-patch routing
+
+Use AskUserQuestion:
+- **"Test commands"** — run affected commands to verify patches work
+- **"View overlays"** — `maestro overlay list`
+- **"Continue"** — done
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No signals found from any source | Verify artifact paths, or provide description |
+| E002 | error | Source artifact not found | Check path exists |
+| E003 | error | No signals map to command deficiencies (all are code bugs) | Use `/maestro-quick` or `/maestro-plan --gaps` instead |
+| E004 | error | Overlay validation failed after 2 retries | Review generated JSON manually |
+| W001 | warning | Some signals skipped (code bugs, not command gaps) | Route to appropriate fix command |
+| W002 | warning | Target command has many existing overlays (≥3) | Consider consolidating overlays |
+| W003 | warning | Scan found no recent workflow artifacts | Check `.workflow/` or provide explicit source |
+</error_codes>
+
+<success_criteria>
+- [ ] Signal sources resolved and signals collected
+- [ ] Each signal classified: command deficiency vs. code bug (only command deficiencies proceed)
+- [ ] Signals mapped to target command + section + mode
+- [ ] Pristine command sources read to verify sections and check existing overlays
+- [ ] Section map with injection points shown and confirmed by user
+- [ ] Overlay JSON written to `~/.maestro/overlays/amend-{slug}.json`
+- [ ] Supplementary docs written to `~/.maestro/overlays/docs/` if needed
+- [ ] `maestro overlay add` exited successfully for each overlay
+- [ ] Target command files contain `<!-- maestro-overlay:amend-{slug}#N hash=... -->` markers
+- [ ] Report shown with overlay details, source traceability, and skipped signals
+- [ ] Skipped code-bug signals routed to appropriate alternative command
+</success_criteria>

package/claude/maestro-flow/commands/lifecycle/analyze.md

@@ -0,0 +1,126 @@
+---
+name: maestro-analyze
+description: Multi-dimensional analysis with CLI exploration, decision extraction, and intent tracking
+argument-hint: "[phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Perform multi-dimensional analysis of a technical proposal, decision, or architecture choice through iterative CLI-assisted exploration and interactive discussion. Produces a discussion timeline (discussion.md) with evolving understanding, multi-perspective findings, Decision Recording Protocol, Intent Coverage tracking, and a final conclusions package with Go/No-Go recommendation.
+
+Combines structured 6-dimension scoring with iterative deepening and decision extraction. Replaces both analysis and decision-capture workflows — produces analysis.md (scoring) AND context.md (Locked/Free/Deferred decisions for plan).
+
+Use `-q` for quick decision extraction only (skip exploration + scoring).
+
+Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyze). Loads issues from issues.jsonl, performs CLI exploration against issue context/location, synthesizes root cause into issue.analysis, and outputs context.md for downstream `plan --gaps`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/analyze.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone mode, no args for milestone-wide.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
+- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
+- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
+- `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
+
+Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/analyze.md' completely.
+
+### --gaps Mode (Issue Root Cause Analysis)
+
+When `--gaps` flag is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard analyze pipeline:
+
+```
+Phase 1: Load issues from .workflow/issues/issues.jsonl
+  - If ISS-ID provided: load single issue
+  - If no ISS-ID: filter issues where status = open | registered
+  - Validate: at least 1 issue loaded, else error E_NO_ISSUES
+
+Phase 2: CLI exploration per issue
+  - For each issue: build exploration prompt from issue.title, description, context, related_files
+  - Run maestro delegate --role analyze --mode analysis with codebase context
+  - Gather affected files, call chains, root cause evidence
+
+Phase 3: Root cause synthesis → write issue.analysis
+  - Parse CLI output into analysis record: { root_cause, affected_files, impact_scope, fix_direction, confidence, analyzed_at, tool, depth }
+  - Write analysis record to issue in issues.jsonl
+  - Append history entry: { action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }
+
+Phase 4: Output context.md for downstream plan --gaps
+  - Aggregate all analyzed issues into context.md with root causes and fix directions
+  - Register ANL artifact in state.json
+```
+
+**Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions). In --gaps mode, context.md contains issue root causes for `plan --gaps` consumption.
+
+**Next-step routing on completion:**
+
+Phase/Milestone scope:
+- Go recommendation, UI work needed → `/maestro-ui-design {phase}`
+- Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
+- No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
+
+Adhoc/Standalone scope:
+- Ready to plan → `/maestro-plan --dir {scratch_dir}`
+- Need more exploration → `/maestro-analyze {topic} -c`
+
+Gaps scope:
+- Issues analyzed → `/maestro-plan --gaps` (plan fix tasks linked to issues)
+- Need more context → `/maestro-analyze --gaps {ISS-ID}` (re-analyze specific issue)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Prompt user for topic text or create roadmap first |
+| W001 | warning | CLI exploration failed | Continue with available context, note limitation |
+| W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
+| W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
+| W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
+| E_NO_ISSUES | error | --gaps but no open/registered issues found | Suggest `/manage-issue-discover` or `/manage-issue create` |
+| E_ISSUE_NOT_FOUND | error | --gaps with ISS-ID but issue not found | Suggest `/manage-issue list` to find valid IDs |
+</error_codes>
+
+<success_criteria>
+Full mode:
+- [ ] CLI exploration completed with code anchors and call chains
+- [ ] discussion.md created with full timeline, TOC, Current Understanding
+- [ ] analysis.md written with all 6 dimensions scored with evidence
+- [ ] conclusions.json created with recommendations and decision trail
+- [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
+
+Gaps mode:
+- [ ] Issues loaded from issues.jsonl (all open/registered, or single ISS-ID)
+- [ ] CLI exploration executed per issue with codebase context
+- [ ] Analysis record attached to each issue in issues.jsonl
+- [ ] context.md written with aggregated root causes for plan --gaps
+
+Both modes (full + quick):
+- [ ] context.md written with all decisions classified as Locked/Free/Deferred
+- [ ] Gray areas identified through phase-specific analysis
+- [ ] Decision Recording Protocol applied to all decisions
+- [ ] Scope creep redirected to Deferred section
+- [ ] Deferred items auto-created as issues (if any)
+- [ ] Artifact registered in state.json with correct scope/milestone/phase
+- [ ] Next step routed (ui-design/plan for Go, brainstorm for No-Go)
+</success_criteria>