// Use when a topic needs structured multi-dimensional investigation before planning or decision-making
Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 6-phase document chain
Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
Use when a confirmed plan is ready for implementation
Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming
Initialize project with auto state detection
Audit current milestone for cross-phase integration gaps
| name | maestro-analyze |
| description | Use when a topic needs structured multi-dimensional investigation before planning or decision-making |
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>
Dual-layer mode:
scope_verdict to route next step. Use before roadmap or for standalone analysis.analyze 1 = Phase 1 of current milestone.Disambiguation rule (mode selection):
^\d+$ (pure digits, e.g. 1, 42) → micro mode (treat as phase number)auth-refactor, improve search) → macro mode (treat as topic)"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).
.workflow/codebase/doc-index.json exists → Read ARCHITECTURE.md for module boundariesmaestro spec load --category arch — load architecture constraintsmaestro wiki search "{topic keywords}" --json → top 5-10 entries as prior knowledgemaestro 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.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-xxxmedium (1-2 subsystems, parallelizable) → suggest /maestro-plan --from analyze:ANL-xxxsmall (single-file or few-file change) → suggest /maestro-plan --from analyze:ANL-xxx
=== 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}
===
End the step by calling the CLI (no text block output):
maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
Status verdicts:
--concerns--reason| 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} |
@~/.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:
Gaps mode:
Both modes (full + quick):
discussion.md and mirrored into context.md "Interview Decisions"