maestro-flow 0.3.15 → 0.3.17

package/.codex/skills/manage-knowhow-capture/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: manage-knowhow-capture
+description: Capture reusable knowledge into .workflow/knowhow/ — session compact, template, recipe, reference, decision, or tip
+argument-hint: "[type] [description] [--lang lang] [--source url] [--tag tag1,tag2]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Capture reusable knowledge into `.workflow/knowhow/`. Six content types: `session` (full session recovery), `template` (code/config pattern), `recipe` (step-by-step guide), `reference` (external doc summary), `decision` (ADR), `tip` (quick note). Auto-detects type or asks user.
+</purpose>
+
+<context>
+$ARGUMENTS — type token followed by description and optional flags.
+
+```bash
+$manage-knowhow-capture
+$manage-knowhow-capture "compact"
+$manage-knowhow-capture "template React form pattern --lang typescript"
+$manage-knowhow-capture "tip Always check state.json before phase operations --tag workflow,state"
+$manage-knowhow-capture "recipe Deploy to production --tag deploy,ops"
+$manage-knowhow-capture "reference Stripe API --source https://docs.stripe.com/api"
+$manage-knowhow-capture "decision Use PostgreSQL over MongoDB --status accepted"
+```
+
+**Types**: `compact` | `template` | `recipe` | `reference` | `decision` | `tip`
+
+**Flags**:
+- `--lang <lang>` — Language for templates (typescript, python, bash, yaml, ...)
+- `--source <url>` — Source URL for references
+- `--tag tag1,tag2` — Categorization tags
+- `--title <title>` — Explicit title
+</context>
+
+<execution>
+
+### Step 1: Validate
+
+Verify `.workflow/` exists (E001). Create `.workflow/knowhow/` if missing.
+
+### Step 2: Detect Type
+
+Parse first token as type. If absent or ambiguous, ask user via AskUserQuestion.
+
+| Token | Type |
+|-------|------|
+| `compact`, `session`, `压缩` | session |
+| `template`, `tpl`, `模板` | template |
+| `recipe`, `rcp`, `配方`, `步骤` | recipe |
+| `reference`, `ref`, `参考` | reference |
+| `decision`, `dcs`, `决策` | decision |
+| `tip`, `note`, `记录` | tip |
+
+### Step 3: Capture Content by Type
+
+**session** (KNW-{YYYYMMDD}-{HHMM}.md):
+Extract from conversation: objective, key decisions, modified files (absolute paths), execution plan (verbatim), pending work, notes. Sections: Session ID, Project Root, Objective, Execution Plan, Working Files, Reference Files, Last Action, Decisions, Constraints, Dependencies, Changes Made, Pending, Notes.
+
+**template** (TPL-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: language (`--lang`), usage context, code content, parameters, dependencies. Sections: Usage, Parameters, Dependencies, Code (fenced block).
+
+**recipe** (RCP-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: goal, prerequisites, numbered steps, expected outcome, common pitfalls, related entries. Sections: Goal, Prerequisites, Steps, Expected Outcome, Common Pitfalls, Related.
+
+**reference** (REF-{YYYYMMDD}-{HHMM}.md):
+Source from `--source` flag (offer WebFetch if URL). Extract: key points, applicable scenarios, quick examples. Sections: Source, Key Points, Applicable Scenarios, Quick Examples.
+
+**decision** (DCS-{YYYYMMDD}-{HHMM}.md):
+Prompt for or extract: context, decision, alternatives (at least 2), rationale, consequences. Sections: Context, Decision, Alternatives Considered (table), Rationale, Consequences, Related.
+
+**tip** (TIP-{YYYYMMDD}-{HHMM}.md):
+Content from remaining arguments. Auto-detect context from recent conversation files. Sections: Content, Context, Tags, Timestamp.
+
+### Step 4: Write File
+
+Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter:
+
+```yaml
+---
+title: {auto or --title}
+type: {type}
+category: {type}
+created: {ISO timestamp}
+tags: [{tags}]
+```
+Plus type-specific: `lang` (template), `source` (reference), `status` (decision).
+
+### Step 5: Confirm
+
+Display: type, ID, file path, and type-specific summary.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first |
+| E002 | error | Template: no code provided after prompt |
+| E003 | error | Recipe: no steps provided after prompt |
+| W001 | warning | No active workflow session — compact captures conversation only |
+| W002 | warning | No explicit plan found — using inferred plan |
+| W003 | warning | `--source` URL could not be fetched — proceeding with manual entry |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/` existence validated; `.workflow/knowhow/` created if missing
+- [ ] Type detected or prompted (all 6 types)
+- [ ] Type-specific content collected (code for template, steps for recipe, etc.)
+- [ ] YAML frontmatter with type-specific fields written
+- [ ] Markdown file written with correct prefix and structured sections
+- [ ] Confirmation displayed with ID, type, category, and file path
+</success_criteria>

package/.codex/skills/manage-learn/SKILL.md

@@ -74,98 +74,44 @@ Validate `--category` if provided (allowed: pattern, antipattern, decision, tool
 
 ### Step 2: Bootstrap Learning Store (on first use)
 
-Check if `.workflow/learning/lessons.jsonl` exists. If not:
-```javascript
-// Create directory and empty files — use Bash + Write (apply_patch cannot create empty files reliably)
-Bash('mkdir -p .workflow/learning && touch .workflow/learning/lessons.jsonl')
-Write('.workflow/learning/learning-index.json', '{"version":1,"entries":[]}\n')
-```
-
-Verify `.workflow/` exists (E001 if not).
+Verify `.workflow/` exists (E001 if not). If `.workflow/learning/lessons.jsonl` missing: create directory, empty `lessons.jsonl`, and initialize `learning-index.json` with `{"version":1,"entries":[]}`.
 
 ### Step 3: Execute Mode
 
 #### Capture Mode
 
-1. **Infer category** from insight text (keyword heuristics, no LLM):
+1. **Infer category** from keywords (no LLM):
 
-| Keywords present in text | Inferred category |
-|--------------------------|-------------------|
+| Keywords | Category |
+|----------|----------|
 | always, should, prefer, best practice | pattern |
 | never, avoid, don't, pitfall, breaks | antipattern |
-| decided, chose, tradeoff, because, reason | decision |
-| tool, library, framework, package, cli | tool |
-| gotcha, surprising, unexpected, watch out | gotcha |
-| technique, approach, method, pattern for | technique |
-
-2. **Auto-link phase**: Read `.workflow/state.json` for current phase (derived from artifact registry). Resolve matching directory slug via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`. `--phase 0` forces null.
-
-3. **Generate stable INS-id**: `INS-{8 lowercase hex}` from `hash(insightText + timestamp)`.
-
-4. **Build lessons.jsonl row**:
-```json
-{
-  "id": "INS-a3f7b2c1",
-  "title": "<first 80 chars of insight>",
-  "summary": "<full insight text>",
-  "source": "manual",
-  "lens": null,
-  "category": "<inferred or explicit>",
-  "tags": ["manual", "<user tags...>"],
-  "phase": "<N or null>",
-  "phase_slug": "<slug or null>",
-  "confidence": "<high|medium|low>",
-  "routed_to": null,
-  "routed_id": null,
-  "created_at": "<ISO>"
-}
-```
+| decided, chose, tradeoff, because | decision |
+| tool, library, framework, package | tool |
+| gotcha, surprising, unexpected | gotcha |
+| technique, approach, method | technique |
 
-5. **Append to lessons.jsonl**:
-```javascript
-// Append single JSON line — Bash echo avoids rewriting the whole file
-Bash(`echo '${JSON.stringify(insightRow)}' >> .workflow/learning/lessons.jsonl`)
-```
-
-6. **Update learning-index.json**: Read, push entry, write back:
-```javascript
-const index = JSON.parse(Read('.workflow/learning/learning-index.json'))
-index.entries.push({ id: insightRow.id, title: insightRow.title, category: insightRow.category, tags: insightRow.tags, phase: insightRow.phase, created_at: insightRow.created_at })
-Write('.workflow/learning/learning-index.json', JSON.stringify(index, null, 2) + '\n')
-```
+2. **Auto-link phase** from `state.json` artifact registry. `--phase 0` forces null.
+3. **Generate INS-id**: `INS-{8 hex}` from `hash(insightText + timestamp)`.
+4. **Build row** with fields: id, title (first 80 chars), summary, source="manual", lens=null, category, tags (includes "manual"), phase, phase_slug, confidence, routed_to=null, created_at.
+5. **Append** JSON line to `lessons.jsonl` (append-only, never rewrite).
+6. **Update** `learning-index.json`: push entry with id, title, category, tags, phase, created_at.
 
 #### List Mode
 
-Read `learning-index.json` entries array. Apply filters (`--tag`, `--category`, `--phase`, `--lens`). Sort newest-first. Display up to `--limit` rows (default 20):
-
-```
-ID              Category     Phase  Tags              Title
-INS-a3f7b2c1   gotcha       3      manual,zod        Zod v4 breaks z.object().strict() API
-INS-b1c2d3e4   pattern      2      manual            Always read state.json before planning
-```
+Read `learning-index.json`, apply filters (`--tag`, `--category`, `--phase`, `--lens`), sort newest-first, display up to `--limit` rows (default 20) as table.
 
 #### Search Mode
 
-Grep across `lessons.jsonl` for the query string. Rank by field match weight: title (3) > tags (2) > summary (1). Display top matches with ID, category, phase, title.
+Grep `lessons.jsonl` for query. Rank by field weight: title (3) > tags (2) > summary (1). Display top matches.
 
 #### Show Mode
 
-Validate INS-id format `INS-[0-9a-f]{8}`. Find row in `lessons.jsonl` where `id` matches. Display full record with all fields. If `routed_to` is set, display the linked artifact path.
+Validate `INS-[0-9a-f]{8}` format. Find matching row, display full record. Show linked artifact if `routed_to` is set.
 
 ### Step 4: Display Confirmation
 
-Capture mode:
-```
-=== INSIGHT CAPTURED ===
-ID:         INS-a3f7b2c1
-Category:   gotcha
-Phase:      3 (phase-03-api-layer)
-Confidence: medium
-Tags:       manual, zod, typescript
-
-Next: $manage-learn "list"  or  $manage-learn "search zod"
-Wiki: maestro wiki list --type lesson  (lessons auto-indexed in wiki graph)
-```
+Capture mode: display ID, category, phase, confidence, tags, and next-step commands (`$manage-learn "list"`, `$manage-learn "search ..."`).
 </execution>
 
 <error_codes>

package/.codex/skills/manage-status/SKILL.md

@@ -28,19 +28,11 @@ Reads from:
 
 ### Step 1: Validate Project
 
-```bash
-# Verify .workflow/ exists
-test -d .workflow || exit 1  # E001: not initialized
-test -f .workflow/state.json || exit 1  # E002: state missing
-```
+Verify `.workflow/` exists (E001) and `state.json` is present (E002).
 
 ### Step 2: Load State Files
 
-Read all state sources:
-- `.workflow/state.json` -- project-level state machine
-- `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/scratch/*/index.json` -- per-phase metadata and progress (resolved via state.json artifact registry)
-- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses (resolved via state.json artifact registry)
+Read: `state.json`, `roadmap.md`, per-phase `scratch/*/index.json`, task files `scratch/*/.task/TASK-*.json` (all resolved via artifact registry).
 
 ### Step 3: Calculate Progress
 
@@ -51,30 +43,7 @@ For each phase directory found:
 
 ### Step 4: Render Dashboard
 
-Display formatted output:
-
-```
-=== PROJECT DASHBOARD ===
-Project: {name} | Status: {state}
-
---- Milestones & Phases ---
-{For each milestone}
-  M{N}: {title}
-  {For each phase}
-    Phase {N}: {title} [{status}] {progress_bar} {completed}/{total} ({pct}%)
-
---- Active Work ---
-Phase {N}: {title}
-  In-progress: {list}
-  Blocked: {list}
-
---- Knowledge Graph ---
-Wiki entries: {total} (spec: {N}, memory: {N}, note: {N}, lesson: {N}, issue: {N})
-Health: {score}/100 | Orphans: {N}
-
---- Next Steps ---
-Based on current state: {suggestion with Skill() reference}
-```
+Display sections: **Milestones & Phases** (per-phase status, progress bars, completion %), **Active Work** (in-progress and blocked tasks), **Knowledge Graph** (wiki entry counts by type, health score, orphans), **Next Steps** (state-based suggestion).
 
 ### Step 5: Suggest Next Steps
 
@@ -87,7 +56,7 @@ Use this decision table to suggest the next action:
 | Phase executed, not verified | `Skill({ skill: "maestro-verify", args: "<N>" })` |
 | Phase verified with gaps | `Skill({ skill: "maestro-plan", args: "<N> --gaps" })` |
 | Phase reviewed PASS/WARN | `Skill({ skill: "quality-test", args: "<N>" })` |
-| UAT passed | `Skill({ skill: "maestro-phase-transition" })` |
+| UAT passed | `Skill({ skill: "maestro-milestone-audit" })` |
 | All milestone phases done | `Skill({ skill: "maestro-milestone-audit" })` |
 </execution>
 

package/.codex/skills/manage-wiki/SKILL.md

@@ -27,7 +27,7 @@ $ARGUMENTS — subcommand and optional flags.
 | `stats` | Graph statistics — type distribution, tag frequency, growth |
 
 **Flags:**
-- `--type <type>` — Filter: spec, memory, note, lesson, issue
+- `--type <type>` — Filter: spec, knowhow, note, lesson, issue
 - `--fix` — Auto-fix issues during cleanup
 - `--json` — JSON output
 </context>

package/.codex/skills/quality-business-test/SKILL.md

@@ -162,19 +162,7 @@ Record results in `.tests/business/test-results-iter-{N}.json`.
 
 ### Step 7: Build Traceability Matrix
 
-Map each result to `REQ-NNN:AC-N`:
-
-```
-FOR each REQ:
-  FOR each AC:
-    ac_status = "passed" if ALL scenarios passed
-                "failed" if ANY failed
-                "blocked" if ANY blocked (none failed)
-                "untested" if no scenarios mapped
-  verdict = "verified" if all MUST+SHOULD passed
-            "partial" if some failed
-            "unverified" if all failed/untested
-```
+Map each result to `REQ-NNN:AC-N`. Per AC: `passed` (all scenarios pass), `failed` (any fail), `blocked` (any blocked, none failed), `untested` (no scenarios). Per REQ verdict: `verified` (all MUST+SHOULD AC passed), `partial` (some failed), `unverified` (all failed/untested).
 
 ### Step 8: Generate Reports
 
@@ -196,7 +184,7 @@ FOR each REQ:
 
 | Result | Suggestion |
 |--------|------------|
-| All requirements verified | Skill({ skill: "maestro-phase-transition", args: "{phase}" }) |
+| All requirements verified | Skill({ skill: "maestro-milestone-audit" }) |
 | Failures found | Skill({ skill: "quality-debug", args: "--from-business-test {phase}" }) |
 | `--re-run` all pass | Skill({ skill: "maestro-verify", args: "{phase}" }) |
 | Low coverage (< 60%) | Skill({ skill: "quality-test-gen", args: "{phase}" }) |

package/.codex/skills/quality-debug/SKILL.md

@@ -139,30 +139,22 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 
 ### Session Initialization
 
-```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const continueMode = $ARGUMENTS.includes('--continue')
-const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
-const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 5
-
-// Parse debug-specific flags
-const fromUatMatch = $ARGUMENTS.match(/--from-uat\s+(\S+)/)
-const parallelMode = $ARGUMENTS.includes('--parallel')
-
-// Clean bug description
-const bugDescription = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--from-uat\s+\S+|--parallel/g, '')
-  .trim()
-
-const slug = bugDescription.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = fromUatMatch ? `${dateStr}-debug-P${fromUatMatch[1]}-${slug}` : `${dateStr}-debug-${slug}`
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-
-Bash(`mkdir -p ${sessionFolder}`)
+```
+Parse from $ARGUMENTS:
+  AUTO_YES       ← --yes | -y
+  continueMode   ← --continue
+  maxConcurrency ← --concurrency | -c N  (default: 5)
+  fromUat        ← --from-uat <phase>  (default: null)
+  parallelMode   ← --parallel
+  bugDescription ← remaining text after flag removal
+
+Derive:
+  slug           ← bugDescription kebab-cased, max 40 chars
+  dateStr        ← UTC+8 YYYYMMDD
+  sessionId      ← fromUat ? "{dateStr}-debug-P{fromUat}-{slug}" : "{dateStr}-debug-{slug}"
+  sessionFolder  ← ".workflow/.csv-wave/{sessionId}"
+
+mkdir -p {sessionFolder}
 ```
 
 ### Phase 1: Input Resolution -> CSV
@@ -179,7 +171,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 | `--parallel` flag present | parallel (implies from-uat, one agent per gap cluster) |
 | Neither flag | standalone (gather symptoms interactively) |
 
-2. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: execute → .summaries/.task/, review → review.json (findings guide hypothesis formation), debug → understanding.md (avoid re-investigation), test → uat.md. Extract conclusions that may affect this debug session.
+2. **Related session discovery**: Query `state.json.artifacts[]` for matching phase+milestone. Extract relevant outputs by type: execute -> .summaries/.task/, review -> review.json (guide hypotheses), debug -> understanding.md (avoid re-investigation), test -> uat.md.
 
 3. **Symptom collection**:
 
@@ -189,15 +181,9 @@ Bash(`mkdir -p ${sessionFolder}`)
 | from-uat | test artifact's uat.md (via registry) | Parse Gaps section, cluster by component |
 | parallel | test artifact's uat.md (via registry) | Same as from-uat, one investigation per cluster |
 
-3. **Hypothesis generation**: For each symptom cluster or bug description:
-   - Analyze code patterns around affected area
-   - Generate 3-5 ranked hypotheses
-   - Each hypothesis becomes a wave 1 CSV row
+3. **Hypothesis generation**: Per symptom cluster, analyze affected code and generate 3-5 ranked hypotheses (each becomes a wave 1 row).
 
-4. **Fix task generation**: For each hypothesis, pre-generate a wave 2 fix row:
-   - `deps` points to the hypothesis ID
-   - `context_from` points to the hypothesis ID
-   - Wave 2 tasks only execute if their hypothesis is confirmed
+4. **Fix task generation**: Pre-generate wave 2 fix row per hypothesis (`deps`/`context_from` -> hypothesis ID). Only executes if hypothesis confirmed.
 
 5. **CSV generation**: Hypothesis rows (wave 1) + fix rows (wave 2).
 
@@ -211,134 +197,60 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 #### Wave 1: Hypothesis Investigation (Parallel)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 1` AND `status == pending`
-3. No prev_context needed (wave 1 has no predecessors)
-4. Write `wave-1.csv`
-5. Execute:
+1. Extract wave 1 pending rows from master `tasks.csv` into `wave-1.csv` (no prev_context needed)
+2. Execute:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
   instruction: buildInvestigationInstruction(sessionFolder),
-  max_concurrency: maxConcurrency,
-  max_runtime_seconds: 600,
+  max_concurrency: maxConcurrency, max_runtime_seconds: 600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["confirmed", "refuted", "inconclusive", "failed"] },
-      findings: { type: "string" },
-      evidence_for: { type: "string" },
-      evidence_against: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
+  output_schema: { id, status: [confirmed|refuted|inconclusive|failed], findings, evidence_for, evidence_against, error }
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
-8. **Filter for wave 2**: Mark wave 2 fix tasks as `skipped` if their hypothesis was `refuted` or `inconclusive`
+3. Merge results into master `tasks.csv`, delete `wave-1.csv`
+4. **Filter for wave 2**: Mark fix tasks as `skipped` if their hypothesis was `refuted` or `inconclusive`
 
 #### Wave 2: Fix Attempts (Parallel, Confirmed Only)
 
-1. Read master `tasks.csv`
-2. Filter rows where `wave == 2` AND `status == pending` (not skipped)
-3. If no confirmed hypotheses, skip wave 2 entirely
-4. Build `prev_context` from wave 1 findings:
-   ```
-   [H1: Null pointer in login handler] CONFIRMED: User object null when DB returns empty...
-   [H3: Stale session token] CONFIRMED: Refresh logic only handles 403, not 401...
-   ```
-5. Write `wave-2.csv` with `prev_context` column
-6. Execute:
+1. If no confirmed hypotheses remain, skip wave 2 entirely
+2. Extract wave 2 pending rows, build `prev_context` from confirmed wave 1 findings
+3. Write `wave-2.csv`, then execute:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-2.csv`,
   id_column: "id",
   instruction: buildFixInstruction(sessionFolder),
-  max_concurrency: maxConcurrency,
-  max_runtime_seconds: 900,
+  max_concurrency: maxConcurrency, max_runtime_seconds: 900,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["fixed", "fix_failed", "failed"] },
-      findings: { type: "string" },
-      fix_applied: { type: "string" },
-      verified: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
-  }
+  output_schema: { id, status: [fixed|fix_failed|failed], findings, fix_applied, verified, error }
 })
 ```
 
-7. Merge results into master `tasks.csv`
-8. Delete `wave-2.csv`
+4. Merge results into master `tasks.csv`, delete `wave-2.csv`
 
 ### Phase 3: Results Aggregation
 
 **Objective**: Generate final results and human-readable report.
 
-1. Read final master `tasks.csv`
-2. Export as `results.csv`
-3. Generate `context.md`:
-
-```markdown
-# Debug Report -- {bug_description}
+1. Export final `tasks.csv` as `results.csv`
 
-## Summary
-- Mode: {standalone | from-uat | parallel}
-- Hypotheses: {total} investigated
-- Confirmed: {confirmed_count}
-- Fixes applied: {fixed_count}
-- Fixes verified: {verified_count}
-
-## Hypothesis Results
-
-### H{N}: {title} [{status}]
-**Hypothesis**: {hypothesis}
-**Evidence For**: {evidence_for}
-**Evidence Against**: {evidence_against}
-**Findings**: {findings}
-
-## Fix Results
-
-### FIX-H{N}: {title} [{status}]
-**Fix Applied**: {fix_applied}
-**Verified**: {verified}
-**Findings**: {findings}
-
-## Root Causes
-{aggregated confirmed hypotheses with evidence}
-
-## Next Steps
-{suggested actions based on results}
-```
+2. **Generate context.md**: Debug report with summary (mode, hypothesis/confirmed/fixed/verified counts), per-hypothesis results (hypothesis, evidence for/against, findings, status), per-fix results (fix applied, verified, findings), aggregated root causes, and next steps.
 
-4. **UAT update** (if --from-uat): For each confirmed hypothesis with fix:
-   - Update `{artifact_dir}/uat.md` gaps with `root_cause`, `fix_direction`, `affected_files`
+3. **UAT update** (if --from-uat): Update `uat.md` gaps with `root_cause`, `fix_direction`, `affected_files` for confirmed hypotheses.
 
-5. **Issue update**: If `.workflow/issues/issues.jsonl` exists:
-   - Update matching issues with status `diagnosed`, add `context.suggested_fix` and `context.notes`
+4. **Issue update**: If `issues.jsonl` exists, update matching issues with status `diagnosed`, add `context.suggested_fix` and `context.notes`.
 
-6. **Register artifact** (phase-scoped only): Append to `state.json.artifacts[]` with `type: "debug"`, `id: DBG-NNN`, `path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}"`, `depends_on: triggering_review_id || exec_art.id`. Output directory is independent scratch.
+5. **Register artifact** (phase-scoped only): Append to `state.json.artifacts[]` with `type: "debug"`, `id: DBG-NNN`, `depends_on: triggering_review_id || exec_art.id`.
 
-7. **Post-debug Knowledge Inquiry** (after root causes confirmed):
-   - **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
-     → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
-   - **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
-     → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
-   - **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
-     → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
-   - If user confirms, append `<spec-entry>` to matching category file via `spec-add` mechanism
+6. **Post-debug Knowledge Inquiry**: Prompt user to capture knowledge when:
+   - Recurring root cause pattern detected -> `/spec-add debug`
+   - Non-obvious fix strategy used -> `/spec-add learning`
+   - Architectural gap identified -> `/spec-add arch`
 
 8. **Next step routing**:
 
@@ -375,11 +287,7 @@ spawn_agents_on_csv({
 
 #### Protocol
 
-1. **Read** `{session_folder}/discoveries.ndjson` before own investigation
-2. **Skip covered**: If discovery of same type + dedup key exists, skip
-3. **Write immediately**: Append findings as found
-4. **Append-only**: Never modify or delete
-5. **Deduplicate**: Check before writing
+Read `discoveries.ndjson` before investigation. Append-only: dedup by type+key before writing, never modify/delete.
 
 ```bash
 echo '{"ts":"<ISO>","worker":"{id}","type":"root_cause","data":{"location":"src/auth/login.ts:42","cause":"null_dereference","severity":"high","confidence":"confirmed"}}' >> {session_folder}/discoveries.ndjson