# Workflow: Analyze

Multi-dimensional iterative analysis with CLI exploration, multi-perspective synthesis, discussion timeline, intent tracking, and decision extraction.

## Pipeline Position

```
maestro-brainstorm (optional upstream)
        ↓ ideas, scored options
maestro-analyze ← THIS
        ↓ analysis.md, discussion.md, conclusions.json, context.md, context-package.json
maestro-plan → maestro-execute → maestro-verify
```

## Architecture

```
Full mode (-q omitted):
  Phase 1:    Setup & Scoping         → session init, dimension selection, discussion.md
              |
  Phase 2:    CLI Exploration          → exploration-codebase.json, explorations.json/perspectives.json
              |                           (cli-explore-agent 3-layer + multi-CLI parallel)
              |
  Phase 3:    Interactive Discussion   → discussion.md rounds (max 5)
              |                           (Decision Recording Protocol, Intent Coverage)
              |
  Phase 4:    Six-Dimension Scoring    → 6 dimensions × 1-5 score + risk matrix
              |
  Phase 5:    Synthesis & Conclusion   → conclusions.json, analysis.md, final discussion.md
              |
  Phase 6:    Decision Extraction      → context.md (Locked/Free/Deferred)
              └── Next Step: plan / issue / done

Quick mode (-q):
  Phase 1:    Setup (minimal)          → load context, skip scoping
              |
  Phase 6:    Decision Extraction      → context.md (Locked/Free/Deferred)
              └── Next Step: plan / done
```

## Arguments

```
$ARGUMENTS: "[phase|topic] [-y] [-c] [-q] [--from <source>]"

(no args)   -- Milestone-wide analysis (requires init + roadmap)
<phase>     -- Phase number (phase-scoped, requires init + roadmap)
<topic>     -- Topic text (adhoc if milestone exists, standalone if not)
-y / --yes  -- Auto mode, skip interactive scoping, auto-deepen
-c / --continue -- Resume from existing session
-q / --quick -- Quick mode, skip exploration + scoring, go straight to decision extraction
--from <source>  -- Load upstream context package (brainstorm:ID, analyze:ID, @file, or path). Replaces --from-brainstorm
```

## Scope Routing

```
Worktree guard: If .workflow/worktree-scope.json exists, reject phase args not in owned_phases.

Auto-bootstrap: Create minimal .workflow/state.json if missing.

Scope determination → OUTPUT_DIR:
  (no args) + milestone + roadmap → scope="milestone", mode="micro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-M{N}-{milestone_slug}/
  (no args) without milestone/roadmap → ERROR E001
  (number) + milestone + roadmap   → scope="phase", mode="micro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-P{N}-{phase_slug}/
  (number) without milestone/roadmap → ERROR
  (text) + milestone               → scope="adhoc", mode="macro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-{topic_slug}/
  (text) without milestone         → scope="standalone", mode="macro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-{topic_slug}/

Macro mode additions (scope="adhoc" or "standalone"):
  - In Step 6 Synthesis, evaluate scope_verdict: "small" | "medium" | "large"
    - large: 3+ independent subsystems or hard serial dependency barriers
    - medium: 1-2 subsystems, parallelizable
    - small: single-file or few-file change
  - Write scope_verdict to context.md conclusions section
  - Include scope_verdict in context-package.json for downstream consumption

Phase-to-Milestone resolution (when scope="phase"):
  FOR each ms in state.json.milestones[]:
    IF phase_number in ms.phases[]:
      target_milestone = ms.id
      BREAK
  IF no match: target_milestone = current_milestone (fallback)

  Use target_milestone (not current_milestone) for:
    - artifact registration (milestone field in Step 8.9)
    - loading prior artifacts (Step 1 context loading)

Create OUTPUT_DIR.
```

## Output Structure

```
{OUTPUT_DIR}/
├── discussion.md              # Full timeline: TOC, rounds, decisions, intent coverage
├── analysis.md                # 6-dimension scoring summary + risk matrix + Go/No-Go (skip in -q)
├── exploration-codebase.json  # Codebase exploration (skip in -q)
├── explorations.json          # Single perspective aggregated findings (skip in -q)
├── perspectives.json          # Multi-perspective findings + synthesis (skip in -q)
├── conclusions.json           # Final synthesis, recommendations, decision trail (skip in -q)
├── context.md                 # Decision extraction: Locked/Free/Deferred decisions for plan
└── context-package.json       # Standardized context package for cross-command consumption
```

---

## Process

### Step 1: Parse Input & Initialize Session

Parse $ARGUMENTS to determine mode and flags:
- `-c` present: locate existing session folder (discussion.md exists), resume from last round
- `-y` present: set AUTO_MODE=true
- `-q` present: set QUICK_MODE=true (skip Steps 2-7, jump to Step 8: Decision Extraction)
- Number (e.g., "3") = phase scope: resolve phase slug from roadmap, output to scratch/{YYYYMMDD}-analyze-P{N}-{phase-slug}/
- Text (e.g., "microservices vs monolith") = adhoc/standalone scope: output to scratch/{YYYYMMDD}-analyze-{slug}/
- Missing/empty = milestone scope (if roadmap exists) or error E001

**Session initialization:**
- Session ID: `ANL-{slug}-{YYYY-MM-DD}`
- Output: `OUTPUT_DIR` (always under `.workflow/scratch/`)

**Load prior context** (milestone/phase scope):
1. Read `.workflow/project.md` — project vision, constraints, Validated requirements (already shipped), Active requirements (current scope)
2. Read `.workflow/roadmap.md` — phase structure and dependencies
3. Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context` (key_decisions, deferred items, blockers)
4. Find prior analyze artifacts from `state.json.artifacts[]` where type=analyze and same milestone → load their `context.md` to skip already-decided areas
5. **Load upstream context** (priority order):
   a. If `--from` specified: resolve source → load `context-package.json` (see §9 of workflow-structure-guide.md)
      - `--from brainstorm:ID` → `state.json.artifacts[type=brainstorm, id=ID].context_package` → load
      - `--from @file` → create import session, delegate extraction → load context-package.json
      - `--from path/` → load `path/context-package.json`
   b. Else: auto-discover from `state.json.artifacts[]` where type=brainstorm and same milestone → if artifact has `context_package` field, load it; else fallback to reading `guidance-specification.md` directly
   
   From loaded context-package:
   - `constraints[status=locked]` → skip these areas (already decided)
   - `constraints[status=open]` → prioritize for analysis
   - `open_questions[]` → seed discussion topics
6. Load project specs: `specs_content = maestro spec load --category arch`

**Load prior context** (adhoc/standalone scope):
1. Read `.workflow/project.md` (if exists) — project vision, Validated requirements, Active requirements, Key Decisions
2. Read `.workflow/state.json` (if exists) → `accumulated_context` (key_decisions, deferred, blockers)
3. Load project specs: `specs_content = maestro spec load --category arch`

**Quick mode routing**: If QUICK_MODE, skip to Step 8 (Decision Extraction) after loading context.

### Step 1.5: Archive Previous Artifacts

Skip if `-c` (resuming — working on existing session).

Before writing any new artifacts, archive existing ones to preserve history:

```
ARCHIVE_TARGETS = ["discussion.md", "analysis.md", "explorations.json", "perspectives.json", "conclusions.json", "exploration-codebase.json"]

If any ARCHIVE_TARGETS exist in OUTPUT_DIR:
  Move each existing target to OUTPUT_DIR/.history/{name}-{YYYY-MM-DDTHH-mm-ss}.{ext}
```

### Step 2: Scoping & Dimension Selection

Skip if `-c` (resuming) or `-y` (auto mode uses defaults).

**Interactive scoping** via single AskUserQuestion (up to 3 questions):

1. **Focus** (multiSelect, header: "分析方向"): Present 3-4 directions from Dimension-Direction Mapping:

   | Dimension | Directions |
   |-----------|-----------|
   | architecture | System Design, Component Interactions, Technology Choices, Design Patterns |
   | implementation | Code Structure, Patterns, Error Handling, Algorithm Analysis |
   | performance | Bottlenecks, Optimization, Resource Utilization, Concurrency |
   | security | Vulnerabilities, Auth, Data Protection, Input Validation |
   | concept | Foundation, Core Mechanisms, Patterns, Trade-offs |
   | comparison | Solution Comparison, Pros/Cons, Technology Evaluation |
   | decision | Criteria, Trade-off Analysis, Risk Assessment, Impact |
   | external_research | Standard Stack, Architecture Patterns, Don't Hand-Roll, Common Pitfalls (external web search) |

   **Auto-suggest `external_research`** when phase goal contains unfamiliar technology keywords or when no codebase patterns exist for the domain (codebase exploration in Step 4.1 returns empty relevant_files).

2. **Perspectives** (multiSelect, header: "分析视角"): Up to 4:

   | Perspective | CLI Tool | Focus |
   |-------------|----------|-------|
   | Technical | gemini | Implementation, code patterns, feasibility |
   | Architectural | claude | System design, scalability, interactions |
   | Business | codex | Value, ROI, stakeholder impact |
   | Domain Expert | gemini | Domain patterns, best practices, standards |

3. **Depth** (single-select, header: "分析深度"):
   - Quick Overview / Standard / Deep Dive

**Auto mode defaults**: all dimensions relevant to topic, single comprehensive perspective, Standard depth.

### Step 3: Initialize discussion.md

Write initial `discussion.md` to output directory:
- Dynamic TOC (updated after each round/phase)
- Session metadata (id, topic, dimensions, perspectives, depth)
- User Intent section (original topic/question for intent tracking)
- Current Understanding block (replaceable — overwritten each round, NOT appended): initialized as "To be populated after exploration"
- Empty discussion timeline
- Dimension selection rationale

### Step 4: CLI Exploration

Codebase exploration FIRST, then (optionally) external research, then CLI analysis.

**Step 4.0: External Research** (only if `external_research` dimension selected)

Orchestrator performs targeted web searches, then hands results to `workflow-phase-researcher` agent for synthesis.

```
1. WebSearch 2-3 queries: "{phase_goal} standard library stack", "architecture patterns best practices", "common pitfalls mistakes"
   Fetch top 1-2 results per query for official docs.

2. Hand raw search output to workflow-phase-researcher agent to synthesize into:
   - ## Standard Stack: concrete library recommendations with versions
   - ## Architecture Patterns: recommended patterns
   - ## Don't Hand-Roll: problems with existing solutions
   - ## Common Pitfalls: mistakes to avoid
   Style: prescriptive ("use X"), cite sources, confidence levels (HIGH/MEDIUM/LOW).
   Agent returns structured markdown only (no file writes).

3. Store agent output as researchContext (in-memory).
```

`researchContext` is passed into Step 4.2 CLI Analysis and Step 8 Decision Extraction.
If `external_research` not selected: `researchContext = null`.

**Step 4.1: Codebase Exploration** (cli-explore-agent)

Spawn cli-explore-agent with 3-layer exploration:

| Layer | Focus | Output |
|-------|-------|--------|
| Layer 1: Module Discovery (Breadth) | Search by topic keywords, identify ALL relevant files, map module boundaries | `relevant_files[]` |
| Layer 2: Structure Tracing (Depth) | Top 3-5 key files: trace call chains 2-3 levels deep, identify data flow | `call_chains[]`, `data_flows[]` |
| Layer 3: Code Anchor Extraction (Detail) | Each key finding: extract code snippet (20-50 lines) with file:line | `code_anchors[]` |

Output: `exploration-codebase.json` (single) or `explorations/{perspective}.json` (multi-perspective, parallel up to 4)

**Step 4.2: CLI Analysis** (AFTER exploration)

Build exploration context from Step 4.1 findings, then spawn CLI analysis.
If `researchContext` is set (from Step 4.0), include it as additional context in each CLI call:

```
// Append to CLI prompt when researchContext exists:
"External research findings (treat as strong recommendations, not laws):
{researchContext}"
```

- **Single perspective**: one comprehensive CLI call with exploration context
- **Multi-perspective** (up to 4): parallel CLI calls per perspective, each with perspective-specific focus

CLI calls use `run_in_background: true`. Wait for results before continuing.

**Step 4.3: Aggregate Findings**

- Consolidate explorations + CLI results
- Multi-perspective: extract synthesis (convergent themes, conflicting views, unique contributions)
- Write to `explorations.json` (single) or `perspectives.json` (multi)

`explorations.json` includes `technical_solutions[]`: `{round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}` — populated throughout Step 5 rounds.

**Step 4.4: Update discussion.md — Round 1**

Append Round 1 to discussion timeline:
- Sources used
- Key findings with code anchors
- Discussion points
- Open questions

**Step 4.5: Initial Intent Coverage Check**

Re-read original User Intent from discussion.md header. Check each intent item against Round 1 findings:
- ✅ addressed
- 🔄 in-progress
- ❌ not yet touched

Append initial Intent Coverage Check to discussion.md.

**Step 4.6: Baseline Confidence Scoring**

Dimensions = the 6 analysis dimensions. Factors (weights): findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Score each factor per dimension from Round 1 results. Append baseline confidence table to discussion.md. Thresholds: <60% 继续深入 | 60-80% 可选 | 80-95% 接近收敛 | >95% 建议收敛.

### Step 5: Interactive Discussion Loop

Max 5 rounds. Each round follows this sequence:

**5.1: Current Understanding Summary** (Round >= 2, BEFORE presenting new findings):
Generate 1-2 sentence recap linking previous round conclusions to current starting point.

**5.2: Present Findings** from latest exploration/analysis

**5.3: Gather Feedback** (AskUserQuestion, single-select, header: "分析反馈"):
- **继续深入**: Deepen analysis — auto or user-specified direction
- **调整方向**: Different focus or specific questions
- **补充信息**: User has additional context, constraints, or corrections
- **分析完成**: Sufficient — exit to Phase 4

**5.4: Process Response** (always record user choice + impact to discussion.md):

| Choice | Action |
|--------|--------|
| 继续深入 | Sub-question (max 4 options: 3 context-driven + 1 heuristic frame-breaker) → CLI/agent exploration → merge findings |
| 调整方向 | Capture new direction → new CLI exploration → Record Decision (old vs new, reason, impact) |
| 补充信息 | Capture user input → integrate → answer questions via CLI if needed → Record corrections |
| 分析完成 | Exit loop → Record why concluding |

**5.5: Update discussion.md** after each round:
- **Append** Round N: user input, direction, Q&A, corrections, new insights
- **Append Technical Solutions** — for every solution proposed, validated, or rejected this round, record immediately using Technical Solution Record Format in `#### Technical Solutions`
- **Replace** `## Current Understanding` block with latest consolidated understanding
- **Update** `## Table of Contents` with links to new sections

**5.6: Round Narrative Synthesis** (append after each round):
```markdown
### Round N: Narrative Synthesis
**起点**: 基于上一轮的 [conclusions/questions]，本轮从 [starting point] 切入。
**关键进展**: [New findings] [confirmed/refuted/modified] 了之前关于 [hypothesis] 的理解。
**决策影响**: 用户选择 [feedback type]，导致分析方向 [adjusted/deepened/maintained]。
**当前理解**: 经过本轮，核心认知更新为 [updated understanding]。
**遗留问题**: [remaining questions driving next round]
```

**5.7: Intent Drift Check** (every round >= 2):
Re-read original User Intent. Check each item:
- ✅ addressed (in Round N)
- 🔄 in-progress
- ⚠️ implicitly absorbed (needs confirmation)
- ❌ not yet discussed

If ❌ or ⚠️ items exist → proactively surface to user at start of next round.

**5.8: Re-score Confidence** (every round):
Re-evaluate factors per dimension. Show delta: `Confidence: {prev}% → {current}% ({±N%}), {weakest_dim} 仍需深入`

**5.9: Quality Mechanisms**:
- **Pressure Pass** (mandatory ≥1 before Step 6): highest-confidence finding → pressure ladder (evidence demand → assumption probe → boundary/tradeoff → root cause check). Record under `#### 压力测试`.
- **Devil's Advocate**: dimension > 0.7 → challenge "如果 [finding] 不成立？" (once per dimension)
- **Scope Minimizer**: findings > 5 + scope expanding → "最小可行结论集？"
- **Stall Detection**: delta < 5% for 2 consecutive rounds → "分析可能停滞，建议切换方向或收敛"

**5.10: Pre-Synthesis Readiness Gate** (on "分析完成"):
Block if: ❌ items without deferral | any dimension < 40% | no pressure pass | unresolved contradictions. If blocked → AskUserQuestion: 补充后继续 or 忽略风险并继续 (record `residual_risks[]`).

**Auto mode (-y)**: auto-deepen ≤3 rounds, readiness gate auto-overrides with residual risk recording.

### Step 6: Six-Dimension Scoring

Using all exploration findings, discussion insights, and user feedback, score across 6 dimensions:

| Dimension | Focus Areas | Score |
|-----------|------------|-------|
| Feasibility | Technical difficulty, team capability, time, tooling | 1-5 |
| Impact | User value, business value, tech debt reduction, DX | 1-5 |
| Risk | Failure modes, security, scalability, regression | 1-5 |
| Complexity | Integration points, dependencies, learning curve, testing | 1-5 |
| Dependencies | External services, internal modules, data, infrastructure | 1-5 |
| Alternatives | 2+ other approaches with tradeoffs | N/A |

Each dimension scored with specific evidence (code refs, data points from exploration).

Each 1-5 score justified by confidence factors from Step 4.6/5.8. Include per-dimension confidence % alongside the score.

Build probability-impact risk matrix from identified risks.

Formulate Go/No-Go/Conditional recommendation with overall confidence %. Write confidence summary (per-dimension scores + overall + pressure pass result + residual risks) to analysis.md.

### Step 7: Synthesis & Conclusion

**7.1: Intent Coverage Verification** (MANDATORY before synthesis):

```markdown
### Intent Coverage Matrix
| # | Original Intent | Status | Where Addressed | Notes |
|---|----------------|--------|-----------------|-------|
| 1 | [intent] | ✅ Addressed | Round N, Conclusion #M | |
| 2 | [intent] | 🔀 Transformed | Round N → M | Original: X → Final: Y |
| 3 | [intent] | ❌ Missed | — | Reason |
```

Gate: ❌ Missed items must be either (a) addressed in additional round or (b) confirmed deferred by user.

**7.2: Consolidate Insights**

Compile from all phases:
- Decision Trail from all rounds
- Key conclusions with evidence + confidence (high/medium/low)
- Recommendations with rationale + priority (high/medium/low) + actionable steps — **merge validated `technical_solutions[]` from explorations.json as high-priority recommendations**
- Open questions, follow-up suggestions
- Write to `conclusions.json`

**7.3: Write analysis.md** (legacy compatible — 6-dimension summary):
- Executive summary with overall assessment
- Per-dimension scores with key evidence
- Dimension summary table
- Risk matrix visualization
- Go/No-Go recommendation with confidence

**7.4: Final discussion.md Update**:
- Conclusions section: summary, ranked key conclusions, prioritized recommendations
- Current Understanding (Final): what established, what clarified/corrected, key insights
- Decision Trail: critical decisions, direction changes timeline, trade-offs
- Intent Coverage Matrix
- Session statistics: rounds, duration, sources, artifacts, decision count

**7.5: Interactive Recommendation Review** (skip in auto mode):

Present recommendations, batch-confirm via AskUserQuestion (max 4 per call, ordered by priority):
- **确认**: Accept as-is → review_status = "accepted"
- **修改**: Adjust scope/steps → review_status = "modified"
- **删除**: Not needed → review_status = "rejected"

Update conclusions.json with review_status for each recommendation.

### Step 8: Decision Extraction

**This step runs ALWAYS** — in full mode after synthesis, in quick mode (`-q`) as the main step.

**8.1: Identify Gray Areas**

Analyze phase goal + loaded context (project.md, roadmap, brainstorm, prior context.md files, exploration findings if available) to find undecided implementation areas.

**Domain-aware gray area generation:**
- Something users SEE: layout, density, interactions, states
- Something users CALL: responses, errors, auth, versioning
- Something users RUN: output format, flags, modes, error handling
- Something users READ: structure, tone, depth, flow
- Something being ORGANIZED: criteria, grouping, naming, exceptions

Generate 3-5 **phase-specific** gray areas.
Skip areas already decided in prior context.md files.
If `guidance-specification.md` loaded: skip MUST/MUST NOT areas (already locked), focus on SHOULD/MAY areas and gaps.
If full mode completed: use exploration findings + scoring to inform gray area quality.

**8.2: Area Selection** (skip if `-y`)

```
AskUserQuestion({
  question: "Which areas need discussion for this phase?",
  options: [
    { label: "Area 1: {title}", description: "{brief description}" },
    { label: "Area 2: {title}", description: "{brief description}" },
    { label: "Area 3: {title}", description: "{brief description}" },
    { label: "All areas", description: "Discuss everything" },
    { label: "Skip", description: "Context is clear enough — no decisions needed" }
  ]
})
```

If "Skip": write minimal context.md (empty Locked/Free/Deferred sections), proceed to Step 9.

**8.3: Deep-Dive Discussion**

For each selected area, conduct multi-round interactive dialog (3-4 questions per area):

```
AskUserQuestion({
  question: "[{area}] {specific question about implementation choice}",
  options: [
    { label: "Option A", description: "{description with tradeoffs}" },
    { label: "Option B", description: "{description with tradeoffs}" },
    { label: "Option C", description: "{description with tradeoffs}" }
  ]
})
```

Record each decision using Decision Recording Protocol.

After questions per area: "More questions about {area}, or move to next?"

**Scope guardrail**: Phase boundary from roadmap.md is FIXED. Discussion clarifies HOW to implement, not WHETHER to add more. If user suggests new capabilities → "That belongs in its own phase. I will note it for later." → capture in Deferred.

**8.4: Classify Decisions**

- **Locked**: firm decisions that cannot be changed during implementation
- **Free**: open for implementation discretion (implementer can choose)
- **Deferred**: postponed to a later phase (captured but not acted on)

**If `researchContext` is set**: for each Free decision area, append a research-backed recommendation:

```
### Free — {area}
Implementer's choice. Research suggests: {relevant finding from researchContext}.
(e.g., "Standard Stack recommends React Query for server state. Common pitfall: avoid mixing with Redux for async.")
```

This makes research findings visible to the planner through context.md without imposing hard constraints.

**8.5: Write context.md**

Write to `OUTPUT_DIR/context.md`:

```markdown
# Context: Phase {NN} -- {PHASE_TITLE}

**Date**: {date}
**Areas discussed**: {list of areas}

## Decisions

### Decision 1: {TITLE}
- **Context**: {what and why}
- **Options**:
  1. {opt1}
  2. {opt2}
- **Chosen**: {selected}
- **Reason**: {rationale}

## Constraints

### Locked
{decisions that are final and must be followed}

### Free
{decisions left to implementer discretion}

### Deferred
{ideas captured but postponed to later phases}

## Code Context
{relevant code references from exploration or discussion}
```

**8.6: Write context-package.json**

Write to `OUTPUT_DIR/context-package.json`:

```jsonc
{
  "$schema": "context-package/1.0",
  "source": {
    "type": "analyze",
    "artifact_id": "{artifact_id}",
    "session_path": "{OUTPUT_DIR relative to .workflow/}",
    "generated_at": "{ISO-8601}"
  },
  "requirements": [],      // From conclusions.json implementation_scope items (if any)
  "constraints": [],        // Locked → { status: "locked" }, Free → { status: "open" }, Deferred → { status: "deferred" }
  "domain": {},             // Inherit from upstream context-package if loaded via --from
  "non_goals": [],          // Deferred items → { title, rationale, ref: "context.md#Deferred" }
  "insights": [],           // From conclusions.json recommendations → { role: "analyzer", area, summary }
  "open_questions": [],     // Free decisions without strong recommendation → { area, question, options[] }
  "references": [
    { "type": "analysis", "path": "context.md" },
    { "type": "conclusions", "path": "conclusions.json" }
  ]
}
```

Extraction mapping from context.md sections:
- Each "Locked" decision → `constraints[]` with `status: "locked"`, `ref: "context.md#Locked"`
- Each "Free" decision → `constraints[]` with `status: "open"`, `ref: "context.md#Free"`
- Each "Deferred" item → `non_goals[]` with `ref: "context.md#Deferred"`
- From `conclusions.json.implementation_scope[]` (if exists) → `requirements[]` with `{ id, title: scope.objective, acceptance: scope.acceptance_criteria, ref: "conclusions.json" }`
- From `conclusions.json.recommendations[]` → `insights[]`

**8.7: Update project.md Key Decisions** (phase mode only)

```
Phase mode only: Append each new Locked decision to .workflow/project.md "## Key Decisions" table.
Row format: | {decision title} | {rationale summary} | Phase {NN} — {date} |
Skip duplicates (match by title).
```

**8.8: Auto-create Issues from Deferred Items**

```
For each Deferred decision, create an issue in .workflow/issues/issues.jsonl:
  id: "ISS-{YYYYMMDD}-{NNN}"
  title: "Deferred: {item.title}"
  status: "deferred", priority: 5, severity: "low"
  source: "analyze", phase_ref: PHASE_NUM
  description: "{item.context} -- Chosen to defer: {item.reason}"
  tags: ["deferred", "analyze"]
```

### Step 8.9: Register Artifact

```
Register artifact in .workflow/state.json:
  id: "ANL-{next sequential 3-digit id}"
  type: "analyze", scope: scope, status: "completed"
  milestone: current_milestone (null if standalone)
  phase: phase_num (null if milestone/adhoc/standalone)
  path: OUTPUT_DIR relative to .workflow/
  context_package: "{OUTPUT_DIR}/context-package.json"   // relative to .workflow/
  harvested: false, created_at: session_start_time, completed_at: now()
Atomic write (tmp + rename).
```

### Step 9: Report & Next Step

Display summary:
- Overall assessment score and recommendation (full mode) or "Quick decision extraction" (quick mode)
- Decisions captured (Locked/Free/Deferred counts)
- Key conclusions (if full mode)
- Session stats

**Next Step Selection** (AskUserQuestion, single-select, header: "Next Step"):
- **快速执行**: Skill({ skill: "maestro-quick", args: "{task_description} --full" }) — build context from conclusions
- **进入规划**: Phase mode → Skill({ skill: "maestro-plan", args: "{phase}" }); Scratch mode → Skill({ skill: "maestro-plan", args: "--dir {output_dir}" }) — plan directly against scratch directory
- **产出Issue**: Convert recommendations to tracked issues
- **完成**: No further action

Handle selection:

| Choice | Action |
|--------|--------|
| 快速执行 | Build `taskDescription` from high/medium priority accepted recommendations. Assemble context from exploration. Invoke Skill immediately. |
| 进入规划 | **Implementation Scoping** (below), then invoke Skill. |
| 产出Issue | For each accepted/modified recommendation: create issue. |
| 完成 | No further action. |

**Implementation Scoping** (for "进入规划" only):

Before invoking maestro-plan, build and persist `implementation_scope` so the planner has concrete "what + done-when" specs:

```
// Step A: Build implementation_scope from accepted/modified recommendations (sorted by priority)
Each scope item:
  objective: rec.action          // WHAT
  rationale: rec.rationale       // WHY
  priority: rec.priority
  target_files: from rec.steps targets + matching code_anchors  // WHERE
  acceptance_criteria: from rec.steps verification/description  // DONE WHEN
  change_summary: "{target}: {description}" per step            // HOW

// Step B: User scope confirmation (skip in auto/quick mode)
AskUserQuestion (single-select, header: "Scope确认"):
  - "确认执行": Proceed to planning
  - "调整范围": Narrow or expand scope
  - "补充标准": Add/refine acceptance criteria

// Step C: Persist implementation_scope to conclusions.json

// Step D: Invoke plan
Phase mode: Skill({ skill: "maestro-plan", args: "{phase}" })
Scratch mode: Skill({ skill: "maestro-plan", args: "--dir {output_dir}" })
```

The planner reads `conclusions.json.implementation_scope` and maps:
- `scope.objective` → task title/description
- `scope.acceptance_criteria` → `convergence.criteria` (seed, planner makes grep-verifiable)
- `scope.target_files` → `files[]` + `read_first[]`
- `scope.priority` → task/wave ordering

Update index.json timestamps.

```
== maestro-analyze complete ==
Session:  {session_id}
Output:   {output_dir}/
Mode:     {full|quick}
Rounds:   {round_count} (full mode only)
Score:    {recommendation} ({confidence}) (full mode only)
Decisions: {decision_count} (Locked: {n}, Free: {n}, Deferred: {n})

Files:
  context.md           — Locked/Free/Deferred decisions for plan
  context-package.json — Standardized context package for cross-command consumption
  discussion.md        — Full discussion timeline (full mode)
  analysis.md          — 6-dimension scoring summary (full mode)
  conclusions.json     — Structured conclusions (full mode)

Next:
  Skill({ skill: "maestro-quick", args: "{task}" })          — Quick execute
  Skill({ skill: "maestro-plan", args: "{phase}" })          — Full phase planning (phase mode)
  Skill({ skill: "maestro-plan", args: "--dir {output_dir}" }) — Plan in scratch dir (scratch mode)
```

---

## Decision Recording Protocol

Record immediately when any occur:

| Trigger | What to Record |
|---------|---------------|
| Direction choice | What chosen, why, alternatives discarded |
| Key finding | Content, impact scope, confidence, hypothesis impact |
| Assumption change | Old → new understanding, reason, impact |
| User feedback | Input, rationale for adoption/adjustment |
| Disagreement/trade-off | Conflicting views, trade-off basis, final choice |
| Scope adjustment | Before/after scope, trigger reason |
| **Technical solution proposed/validated/rejected** | Solution description, rationale, alternatives considered, status |

**Decision Record Format**:
```
> **Decision**: [Description]
> - **Context**: [Trigger]
> - **Options considered**: [Alternatives]
> - **Chosen**: [Approach] — **Reason**: [Rationale]
> - **Rejected**: [Why other options were discarded]
> - **Impact**: [Effect on analysis]
```

**Technical Solution Record Format**:
```
> **Solution**: [Description — what approach, pattern, or implementation]
> - **Status**: [Proposed / Validated / Rejected]
> - **Problem**: [What problem this solves]
> - **Rationale**: [Why this approach]
> - **Alternatives**: [Other options considered and why not chosen]
> - **Evidence**: [file:line or code anchor references]
> - **Next Action**: [Follow-up required or none]
```

## Discussion Timeline (discussion.md)

Each round appends:
- User feedback and direction choice
- New findings with code anchors
- Narrative Synthesis (起点 → 关键进展 → 决策影响 → 当前理解 → 遗留问题)
- Intent Coverage Check (Round >= 2)

Replaceable blocks (overwritten each round):
- `## Current Understanding` — latest consolidated understanding
- `## Table of Contents` — updated with new section links

## Six Dimensions

| Dimension | Focus Areas |
|-----------|------------|
| Feasibility | Technical difficulty, team capability, time, tooling |
| Impact | User value, business value, tech debt reduction, DX |
| Risk | Failure modes, security, scalability, regression |
| Complexity | Integration points, dependencies, learning curve, testing |
| Dependencies | External services, internal modules, data, infrastructure |
| Alternatives | 2+ other approaches with tradeoffs |

## Key Design Principles

1. **Iterative Deepening**: Multi-round discussion (max 5) with user feedback steering direction
2. **CLI-Assisted Exploration**: cli-explore-agent for codebase + multi-CLI parallel analysis
3. **Discussion Timeline**: discussion.md as living document — rounds appended, Current Understanding replaced
4. **Decision Recording Protocol**: Immediate capture of decisions, findings, assumption changes
5. **Intent Coverage Tracking**: Original user intent checked every round (✅🔄⚠️❌)
6. **Six-Dimension Scoring**: Feasibility, Impact, Risk, Complexity, Dependencies, Alternatives
7. **Multi-Perspective Synthesis**: Up to 4 perspectives with convergent/conflicting/unique extraction
8. **Decision Extraction**: Gray area identification → interactive discussion → Locked/Free/Deferred classification → context.md
9. **Dual Depth**: Full mode (explore→score→decide) or Quick mode (-q, decide only)

## Quality Criteria

**Full mode:**
- All 6 dimensions analyzed with evidence-backed scores
- Discussion timeline has narrative synthesis per round
- Decision Recording Protocol applied consistently
- Intent Coverage verified with no unresolved ❌ items
- Risk matrix populated with identified risks
- At least 2 alternatives compared with tradeoffs
- Go/No-Go/Conditional recommendation with confidence level
- Code references included where relevant (file paths, line numbers)
- Confidence tracking initialized and re-scored each round
- Readiness gate checked before synthesis (Step 5.10)
- Pressure pass completed ≥ 1 time before Step 6
- Confidence summary with factor decomposition in analysis.md

**Both modes (full + quick):**
- context.md written with all decisions classified as Locked/Free/Deferred
- context-package.json written with constraints, requirements, insights, and open_questions
- Gray areas identified through phase-specific analysis
- Scope creep redirected to Deferred section
- Every decision follows Context/Options/Chosen/Reason protocol
- Prior context loaded and applied (no re-asking decided questions)
- Upstream context loaded via `--from` when specified (context-package.json consumed)

## Error Handling

| Error | Resolution |
|-------|------------|
| cli-explore-agent fails | Continue with available context, note limitation |
| CLI timeout | Retry with shorter prompt, or skip perspective |
| Max rounds reached | Force synthesis, offer continuation |
| No relevant findings | Broaden search, ask user for clarification |
| Session folder conflict | Append timestamp suffix |
