maestro-flow 0.3.46 → 0.3.48

package/.claude/commands/learn-retro.md

@@ -12,289 +12,146 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Unified retrospective that combines git activity analysis and decision quality evaluation into a single command with lens-based selection. Works on raw git history and wiki/spec data — does not require completed phase artifacts (unlike `quality-retrospective`).
+Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
 
-Two lenses, usable independently or together:
-- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trend tracking
-- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation, lifecycle classification
-
-All insights persist to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-session queryability via `manage-learn`.
+All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
-Arguments: $ARGUMENTS
-
-**Lens selection:**
-- `--lens git` — Git activity retrospective only
-- `--lens decision` — Decision evaluation only
-- `--lens all` — Both lenses (default)
-
-**Git lens flags:**
-- `--days N` — Time window in days (default: 7)
-- `--author <name>` — Filter commits by author name (substring match)
-- `--area <path>` — Scope to files under a specific directory
-- `--compare` — Compare against the previous retro report if one exists
-
-**Decision lens flags:**
-- `--phase N` — Decisions from phase N's context and related specs
-- `--tag <tag>` — Decisions tagged with specific tag in wiki/specs
-- `--id <id>` — Single decision by wiki ID or specs/learnings.md INS-id
-
-**Storage written:**
-- `.workflow/knowhow/KNW-retro-{YYYY-MM-DD}.md` — Unified human-readable report
-- `.workflow/knowhow/KNW-retro-{YYYY-MM-DD}.json` — Structured metrics (machine-readable)
-- `.workflow/knowhow/specs/learnings.md` — Appended `<spec-entry>` blocks (source: "retro-git" or "retro-decision")
-
-**Storage read:**
-- `.workflow/state.json` — Current phase context (optional)
-- `.workflow/knowhow/KNW-retro-*.json` — Prior retro for trend comparison
-- `.workflow/knowhow/specs/learnings.md` — Existing insights for dedup
-- `maestro wiki list --type spec --json` — Spec entries (decision lens)
-- `.workflow/specs/architecture-constraints.md` — Documented architectural decisions (decision lens)
-- Phase context with Locked/Free/Deferred decisions (decision lens) — resolve via `state.json.artifacts[]` scratch paths
-</context>
+$ARGUMENTS — lens selection and scope flags.
 
-<execution>
+**Lens**: `--lens git` | `--lens decision` | `--lens all` (default: all)
 
-### Stage 1: Parse Arguments & Select Lenses
-- Parse `--lens` flag: `git`, `decision`, or `all` (default: `all`)
-- Extract lens-specific flags
-- Check `.workflow/knowhow/` exists; bootstrap if missing
+**Git lens flags**: `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare` (vs prior retro)
+**Decision lens flags**: `--phase N`, `--tag <tag>`, `--id <id>` (single decision by wiki/INS id)
 
-Display banner:
-```
-============================================================
-  LEARN RETRO
-============================================================
-  Lens:    {git | decision | all}
-  Scope:   {days/author/area for git} {phase/tag/id for decision}
-```
+**Storage write**:
+- `.workflow/knowhow/KNW-retro-{date}.md` — unified report
+- `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
+- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
 
----
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+</context>
 
-### Stage 2: Git Lens (skip if --lens decision)
+<state_machine>
 
-#### 2a: Gather Raw Data (parallel git commands)
-Run ALL these git commands in parallel:
+<states>
+S_PARSE       — 解析 lens + flags                           PERSIST: —
+S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
+S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
+S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
+S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+</states>
 
-```bash
-# Commit stats with author, timestamp, subject, files changed
-git log --since="<start-date>T00:00:00" --format="%H|%aN|%ae|%ai|%s" --shortstat
+<transitions>
 
-# Per-commit numstat for test vs production LOC split
-git log --since="<start-date>T00:00:00" --format="COMMIT:%H|%aN" --numstat
+S_PARSE:
+  → S_GIT         WHEN: lens == git OR all               DO: ensure .workflow/knowhow/ exists (mkdir -p)
+  → S_DECISION    WHEN: lens == decision                  DO: ensure .workflow/knowhow/ exists (mkdir -p)
 
-# Timestamps for session detection (sorted)
-git log --since="<start-date>T00:00:00" --format="%at|%aN|%ai|%s" | sort -n
+S_GIT:
+  → S_DECISION    WHEN: lens == all                          DO: A_GIT_ANALYSIS
+  → S_REPORT      WHEN: lens == git                          DO: A_GIT_ANALYSIS
 
-# File hotspots (most frequently changed files)
-git log --since="<start-date>T00:00:00" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+S_DECISION:
+  → S_REPORT      DO: A_DECISION_ANALYSIS
 
-# Per-author commit counts
-git shortlog --since="<start-date>T00:00:00" -sn --no-merges
-```
+S_REPORT:
+  → S_PERSIST     DO: write KNW-retro-{date}.md + .json
 
-Apply `--author` and `--area` filters if provided.
-
-#### 2b: Compute Metrics
-| Metric | Computation |
-|--------|-------------|
-| Commits | Count of non-merge commits |
-| Contributors | Unique author count |
-| Total insertions / deletions | Sum from shortstat |
-| Net LOC | insertions - deletions |
-| Test LOC (insertions) | Sum insertions for test files from numstat |
-| Test ratio | test_insertions / total_insertions x 100% |
-| Churn rate | Files changed >2 times / total unique files |
-| Active days | Distinct dates with commits |
-
-#### 2c: Detect Work Sessions
-Cluster commits by >2hr gaps in timestamps:
-- Per session: start time, end time, duration, commit count, primary focus area
-- Compute: total sessions, avg session duration, avg LOC/session-hour
-
-#### 2d: Per-Author Breakdown
-For each author:
-- Commit count, LOC added/removed, top 3 file areas
-- Test ratio (their test LOC / their total LOC)
-- Session count and patterns
-
-#### 2e: Trend Comparison (if --compare or prior report exists)
-- Find most recent `.workflow/knowhow/KNW-retro-*.json`
-- Compute deltas: commits, LOC, test ratio, churn rate, session count
-- Flag significant changes (>20% delta) as trend highlights
-
-#### 2f: Distill Git Insights
-- **High churn files** (changed >3 times): instability signal
-- **Low test ratio areas** (<20%): testing gap
-- **Session patterns**: scattered vs deep sessions
-- **Area drift**: commits not aligned with current roadmap phase
-
-Each insight: title, description, category (pattern/antipattern/technique), tags, confidence.
+S_PERSIST:
+  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
 
----
+</transitions>
 
-### Stage 3: Decision Lens (skip if --lens git)
+<actions>
 
-#### 3a: Collect Decisions (parallel)
-```bash
-maestro wiki search "decision" --json
-maestro wiki list --type spec --json
-git log --oneline --all --grep="decision\|chose\|decided\|architecture" -20
-```
+### A_GIT_ANALYSIS
 
-Also read:
-- `.workflow/specs/architecture-constraints.md` — grep for `<spec-entry` blocks with `roles="plan"`
-- Phase context files — resolve via `state.json.artifacts[]` scratch paths — scan for "Locked:", "Deferred:" sections
-- `.workflow/knowhow/specs/learnings.md` — filter entries with `keywords` containing "decision"
-
-Apply scope filter (--phase, --tag, --id).
-
-#### 3b: Build Decision Registry
-Per decision:
-```json
-{
-  "id": "source id",
-  "title": "what was decided",
-  "source": "wiki|spec|phase-context|knowhow|git",
-  "date": "when decided",
-  "rationale": "why",
-  "alternatives": "what was considered",
-  "phase": "which phase",
-  "implementation_evidence": ["file paths from git"]
-}
+**Parallel git commands**:
+```bash
+git log --since="{start}" --format="%H|%aN|%ae|%ai|%s" --shortstat
+git log --since="{start}" --format="COMMIT:%H|%aN" --numstat
+git log --since="{start}" --format="%at|%aN|%ai|%s" | sort -n
+git log --since="{start}" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+git shortlog --since="{start}" -sn --no-merges
 ```
+Apply --author and --area filters.
 
-#### 3c: Multi-Perspective Evaluation
-Spawn 3 Agents in a single message:
-
-**Agent 1 — Technical Soundness:**
-- Does implementation match stated intent?
-- Has technical context changed since decision was made?
-- Grade: sound / degraded / violated
+**Compute metrics**:
 
-**Agent 2 — Cost Assessment:**
-- What complexity did this decision add?
-- Is it creating coupling or tech debt?
-- Grade: low-cost / acceptable / expensive / debt-creating
-
-**Agent 3 — Alternative Hindsight:**
-- With what we know now, was this the right call?
-- Would reversing be feasible?
-- Grade: confirmed / questionable / should-revisit
-
-#### 3d: Classify Decision Lifecycle
-| Status | Criteria |
+| Metric | Formula |
 |--------|---------|
-| **Validated** | Sound + Low/Acceptable cost + Confirmed |
-| **Aging** | Sound but Expensive + Confirmed |
-| **Questionable** | Degraded or Violated + Questionable |
-| **Stale** | Any + Should-revisit |
-| **Reversed** | Code contradicts the decision |
-
-#### 3e: Generate Recommendations
-- **Aging**: flag for tech debt review
-- **Questionable**: create issue for investigation
-- **Stale**: suggest decision refresh
-- **Reversed**: suggest documenting the reversal
+| Test ratio | test_insertions / total_insertions * 100% |
+| Churn rate | files changed >2x / total unique files |
+| Sessions | Cluster commits by >2hr gaps in timestamps |
+| LOC/session-hour | net_loc / total_session_hours |
 
----
+**Per-author breakdown**: commits, LOC, top 3 areas, test ratio, session count.
 
-### Stage 4: Unified Report
+**Trend** (if --compare or prior KNW-retro-*.json exists): compute deltas, flag >20% changes.
 
-Write `.workflow/knowhow/KNW-retro-{date}.md`:
+**Distill insights**: high churn files (instability), low test ratio areas (<20%), session patterns, area drift vs roadmap.
 
-```markdown
-# Retrospective: {date}
-**Lenses:** {active lenses} | **Period:** {days}d
+### A_DECISION_ANALYSIS
 
-## Git Activity  (if git lens active)
-### Metrics
-| Metric | Value | Trend |
-|--------|-------|-------|
-| Commits | N | +/-% |
-| ...
-
-### Work Sessions
-{session timeline}
-
-### File Hotspots
-{top 10 most-changed files}
-
-### Per-Author
-{author breakdown table}
+**Collect** (parallel):
+```bash
+maestro wiki search "decision" --json
+maestro wiki list --type spec --json
+git log --oneline --all --grep="decision\|chose\|decided" -20
+```
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Apply --phase/--tag/--id filters.
 
-## Decision Health  (if decision lens active)
-### Dashboard
-| Status | Count | Decisions |
-|--------|-------|-----------|
-| Validated | N | {list} |
-| Aging | N | {list} |
-| ...
+**Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
 
-### Per-Decision Evaluation
-{detailed evaluations}
+**Evaluate** — spawn 3 Agents in single message:
 
-## Combined Insights
-{merged insights from both lenses, deduplicated}
+| Agent | Dimension | Grades |
+|-------|-----------|--------|
+| Technical Soundness | Implementation matches intent? Context changed? | sound / degraded / violated |
+| Cost Assessment | Complexity added? Coupling/debt? | low-cost / acceptable / expensive / debt-creating |
+| Alternative Hindsight | Right call with current knowledge? Reversible? | confirmed / questionable / should-revisit |
 
-## Recommended Actions
-1. {action}: {reason}
-```
+**Classify lifecycle**:
 
-Write `.workflow/knowhow/KNW-retro-{date}.json` with structured data.
+| Status | Criteria |
+|--------|---------|
+| Validated | sound + low/acceptable + confirmed |
+| Aging | sound + expensive + confirmed |
+| Questionable | degraded/violated + questionable |
+| Stale | any + should-revisit |
+| Reversed | code contradicts decision |
 
----
+**Recommend**: Aging → tech debt review, Questionable → create issue, Stale → refresh, Reversed → document reversal.
 
-### Stage 5: Persist
-1. Write report files
-2. Append insights as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "<kw>"`:
-   - Git insights: source="retro-git", roles per insight type
-   - Decision insights: source="retro-decision", roles="plan" (merge "decision" into keywords)
-   - Stable INS-id from `hash(lens + metric_or_decision + date)`
-4. Display summary
+</actions>
 
-**Next-step routing:**
-- Browse insights → `/manage-learn list --tag retro`
-- Deep dive on high-churn file → `/learn-follow <path>`
-- Fix test gaps → `/quality-auto-test <area>`
-- Create issue for questionable decision → `/manage-issue create ...`
-- Investigate stale decision → `/learn-investigate <question>`
-- Full phase retrospective → `/quality-retrospective`
-</execution>
+</state_machine>
 
 <error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Not inside a git repository (git lens) | Navigate to a git repo directory |
-| E002 | error | No commits found in time window (git lens) | Increase --days or check filters |
-| E003 | error | No decisions found in any source (decision lens) | Check wiki/specs content, or provide --id |
-| E004 | error | --id not found in wiki or knowhow (decision lens) | Verify the decision ID exists |
-| W001 | warning | `.workflow/knowhow/` not found, bootstrapping | Auto-created; proceed normally |
-| W002 | warning | No prior retro report for comparison | Skip trend section; first retro establishes baseline |
-| W003 | warning | One perspective agent failed — partial evaluation (decision lens) | Proceed with available perspectives |
-| W004 | warning | No git implementation evidence for a decision | Evaluation is theoretical only |
-| W005 | warning | Phase context files not found (decision lens) | Skip phase-context decisions |
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Not in git repo (git lens) | Navigate to git repo |
+| E002 | No commits in window (git lens) | Increase --days |
+| E003 | No decisions found (decision lens) | Check wiki/specs or provide --id |
+| E004 | --id not found in wiki or knowhow | Verify the decision ID exists |
+| W002 | No prior retro for comparison | Skip trend; first retro = baseline |
+| W003 | One perspective agent failed | Proceed with available perspectives |
 </error_codes>
 
 <success_criteria>
-- [ ] Lens selection parsed correctly (git / decision / all)
-- [ ] Git lens (if active):
-  - [ ] All git commands executed successfully
-  - [ ] Metrics computed: commits, LOC, test ratio, churn rate, sessions
-  - [ ] Sessions detected with >2hr gap clustering
-  - [ ] Per-author breakdown generated
-  - [ ] Trend comparison computed if prior report exists
-  - [ ] At least 1 actionable insight distilled
-- [ ] Decision lens (if active):
-  - [ ] Decisions collected from available sources
-  - [ ] Scope filter applied correctly
-  - [ ] 3 perspective agents spawned in parallel
-  - [ ] Each decision classified by lifecycle status
-  - [ ] Recommendations generated for non-Validated decisions
-- [ ] Unified report written to `KNW-retro-{date}.md`
-- [ ] Structured data written to `KNW-retro-{date}.json`
-- [ ] `specs/learnings.md` appended with `<spec-entry>` blocks (stable INS-ids)
-- [ ] No files modified outside `.workflow/knowhow/`
-- [ ] Summary displayed with next-step routing
+- [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
+- [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
+- [ ] Unified report + structured JSON written
+- [ ] specs/learnings.md appended with stable INS-ids
 </success_criteria>
+
+<next_step_routing>
+- Browse insights → `/manage-learn list --tag retro`
+- Deep dive churn → `/learn-follow <path>`
+- Fix test gaps → `/quality-auto-test <area>`
+- Investigate stale decision → `/learn-investigate <question>`
+</next_step_routing>

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

@@ -12,151 +12,111 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Structured second-opinion workflow for code, decisions, or plans. Three modes inspired by gstack `/codex`:
+Structured second-opinion on code, decisions, or plans. Three modes:
+- **review** (default): 3 parallel agents (pragmatist, purist, strategist)
+- **challenge**: single adversarial agent — break assumptions, propose alternatives
+- **consult**: interactive Q&A — agent studies target, answers your questions
 
-- **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 `specs/learnings.md` as `<spec-entry>` blocks.
+Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
 </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/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md` — Opinion report
-- `.workflow/knowhow/specs/learnings.md` — New `<spec-entry>` blocks from analysis (source: "second-opinion")
-
-**Storage read:**
-- Target content (file, wiki entry, diff, or plan)
-- `.workflow/specs/` — Project conventions for context
-- `maestro wiki search` — Related knowledge entries
-- `.workflow/knowhow/specs/learnings.md` — Prior insights about the topic
+$ARGUMENTS — target and optional mode flag.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path | Read file content |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
+| Phase number | Resolve via state.json.artifacts[] → plan.json |
+
+**Flags**: `--mode review|challenge|consult` (default: review)
+
+**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro wiki search "<target topic>"` for related entries.
+
+**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
 </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: "spec-load" })` silently to get project conventions
-- Search wiki: `maestro wiki search "<target topic>"` for related entries (top 5)
-- Search insights: search `specs/learnings.md` 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
+<state_machine>
+
+<states>
+S_RESOLVE    — 解析 target                          PERSIST: —
+S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
+S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
+S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
+S_PERSIST    — 写文件、append specs/learnings.md      PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved                DO: read target content
+  → S_RESOLVE     WHEN: unresolvable                   DO: AskUserQuestion for clarification
+
+S_CONTEXT:
+  → S_EXECUTE     DO: load specs + wiki search (optional, proceed without)
+
+S_EXECUTE:
+  → S_SYNTHESIZE  WHEN: mode == review                 DO: A_REVIEW
+  → S_SYNTHESIZE  WHEN: mode == challenge              DO: A_CHALLENGE
+  → S_SYNTHESIZE  WHEN: mode == consult                DO: A_CONSULT
+
+S_SYNTHESIZE:
+  → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
+
+S_PERSIST:
+  → END           DO: write KNW-opinion + append <spec-entry> blocks to specs/learnings.md
+
+</transitions>
+
+<actions>
+
+### A_REVIEW
+Spawn 3 Agents in single message:
+
+| Agent | Focus | Question |
+|-------|-------|----------|
+| Pragmatist | simplicity, YAGNI, maintenance | "Simplest thing that works? Maintenance burden?" |
+| Purist | correctness, edge cases, type safety | "What assumptions can be violated?" |
+| Strategist | scalability, architecture alignment | "Supports future growth? Fits architecture?" |
+
+Each returns: persona, verdict (approve/concern/reject), confidence, findings[{severity, description, location, suggestion}], summary.
+
+### A_CHALLENGE
+Spawn 1 adversarial Agent:
+- Find weakest assumption
+- Propose concrete breaking scenario
+- Identify single biggest risk
+- Suggest alternative approach
+- Apply forcing questions: "What invalidates this?", "Simplest thing that breaks this?", "What would you regret in 6 months?", "What implicit contract isn't enforced?"
+
+### A_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/knowhow/KNW-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 as `<spec-entry>` blocks to `specs/learnings.md` via `maestro spec add learning --body "<content>" --keywords "second-opinion,{mode},{target-slug}"`
-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>
+1. Agent studies target
+2. Display "Target loaded. What would you like to know?"
+3. AskUserQuestion → Agent answers with code refs → repeat until "done"
+4. Compile Q&A into report
+
+</actions>
+
+</state_machine>
 
 <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 |
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Unknown --mode value | Use: review, challenge, or consult |
+| W001 | One review agent failed | Proceed with available perspectives |
 </error_codes>
 
 <success_criteria>
-- [ ] Target resolved and content loaded
-- [ ] Context gathered (specs, wiki, knowhow)
-- [ ] 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 `KNW-opinion-{slug}-{date}.md`
-- [ ] Non-trivial findings appended to `specs/learnings.md` as `<spec-entry>` blocks
-- [ ] No files modified outside `.workflow/knowhow/`
-- [ ] Summary displayed with verdict and next-step routing
+- [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
+- [ ] Synthesis with agreements, disagreements, verdict
+- [ ] Report written + findings appended to specs/learnings.md
 </success_criteria>
+
+<next_step_routing>
+- Create issue → `/manage-issue create <description>`
+- Decompose patterns → `/learn-decompose <path>`
+- Follow code → `/learn-follow <path>`
+</next_step_routing>