maestro-analyze

name	maestro-analyze
description	Use when a topic needs structured multi-dimensional investigation before planning or decision-making

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.

Pipeline position: downstream of maestro-grill, maestro-brainstorm, and maestro-blueprint (optional upstream enrichment); upstream of maestro-plan and maestro-roadmap (consumes analysis context).

<required_reading> @~/.maestro/workflows/analyze.md </required_reading>

<deferred_reading>

• state.json — read when registering artifact
• issue-gaps-analyze.md — read when --gaps is triggered </deferred_reading>

$ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no args for milestone-wide.

Dual-layer mode:

• Macro mode (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with scope_verdict to route next step. Use before roadmap or for standalone analysis.
• Micro mode (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. analyze 1 = Phase 1 of current milestone.

Disambiguation rule (mode selection):

• First positional arg matches ^\d+$ (pure digits, e.g. 1, 42) → micro mode (treat as phase number)
• First positional arg is non-numeric text (e.g. auth-refactor, improve search) → macro mode (treat as topic)
• No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
• Mixed input like "1 phase" is treated as text → macro mode (only bare numerics trigger micro)

Flags:

Flag	Effect	Default
-y / --yes	Auto mode — skip interactive scoping, use recommended defaults, auto-deepen	false
-c / --continue	Resume from existing session (auto-detect session folder + discussion.md)	false
-q / --quick	Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)	false
--from <source>	Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path)	—
--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:

Input	Mode	Scope
Pure digits (e.g. 1, 42)	micro	Phase-level deep analysis
Non-numeric text (e.g. auth-refactor)	macro	Topic impact surface
No positional arg + roadmap	micro	Milestone-wide
No positional arg + no roadmap	macro	Fallback
--gaps [ISS-ID]	gaps	Issue root cause analysis

Output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Output Structure section).

Pre-load

1. Codebase docs: IF .workflow/codebase/doc-index.json exists → Read ARCHITECTURE.md for module boundaries
2. Specs: maestro spec load --category arch — load architecture constraints
3. Wiki search: maestro wiki search "{topic keywords}" --json → top 5-10 entries as prior knowledge
4. All optional — proceed without if unavailable (log warning)

Role Knowledge

maestro wiki list --category debug → select relevant → maestro wiki load

<interview_protocol> Follows @~/.maestro/workflows/interview-mechanics.md standard.

Interaction mode: convergent menu-driven Decision tree (strict order): scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold Scope guard: only analyze decisions; do not prejudge plan/execute concerns Writeback target: discussion.md (top table) + context.md "Interview Decisions" Additional search sources: issues.jsonl (--gaps mode), roadmap.md Additional skip conditions: input is already specific (explicit phase number or unambiguous topic) Exit condition: all decision points settled → finalize session metadata </interview_protocol>

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.

scope_verdict (added to context.md in Step 6 Synthesis for macro/adhoc/standalone scopes):

• large (3+ independent subsystems or hard serial dependencies) → suggest /maestro-roadmap --from analyze:ANL-xxx
• medium (1-2 subsystems, parallelizable) → suggest /maestro-plan --from analyze:ANL-xxx
• small (single-file or few-file change) → suggest /maestro-plan --from analyze:ANL-xxx

### Standalone report

=== ANALYSIS READY ===
Artifact: ANL-{id}
Scope: {micro|macro|adhoc|gaps}
Go/No-Go: {GO|NO-GO|CONDITIONAL}
Confidence: {high|medium|low}
Outputs: analysis.md, context.md, conclusions.json, discussion.md
Session dir: {output_dir}
===

Ralph-invoked completion

End the step by calling the CLI (no text block output):

maestro ralph complete <idx> --status {STATUS} [--evidence {path}]

Status verdicts:

• DONE — Normal completion
• DONE_WITH_CONCERNS — Completed with caveats; pass --concerns
• NEEDS_RETRY — Tooling error / transient issue; ralph will retry
• BLOCKED — External hard blocker; pass --reason

Next-step routing

Condition	Suggestion
Phase/Milestone scope, Go, UI work needed	/maestro-impeccable build {target}
Phase/Milestone scope, Go, ready to plan	/maestro-plan or /maestro-plan {phase}
Phase/Milestone scope, No-Go	Revisit requirements or /maestro-brainstorm {topic}
Macro/Adhoc, scope_verdict = large	/maestro-roadmap --from analyze:ANL-xxx
Macro/Adhoc, scope_verdict = medium/small	/maestro-plan --from analyze:ANL-xxx
Need more exploration	/maestro-analyze {topic} -c
Gaps scope, issues analyzed	/maestro-plan --gaps
Gaps scope, need more context	/maestro-analyze --gaps {ISS-ID}

Session seal

@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}

<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)
• Confidence tracking initialized (Step 4.6) and re-scored each round (Step 5.8)
• Readiness gate checked before synthesis (Step 5.10)
• Pressure pass completed ≥ 1 time before Step 6
• Confidence summary with factor decomposition written to analysis.md

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):

• Interactive mode: interview decision table written to discussion.md and mirrored into context.md "Interview Decisions"
• 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 (impeccable/plan for Go, brainstorm for No-Go)
• Session sealed via finish-work (archive.json written, optional spec/knowhow extraction) </success_criteria>