maestro-analyze

<purpose>
Multi-dimensional analysis of a proposal, decision, or architecture choice via CLI-assisted exploration and interactive discussion. Produces analysis.md (6-dimension scoring), context.md (Locked/Free/Deferred decisions), conclusions.json, and discussion.md with Go/No-Go recommendation. Use `--gaps` for issue root cause analysis feeding `plan --gaps`.
</purpose>

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

<deferred_reading>
- [state.json](~/.maestro/templates/state.json) — read when registering artifact
- [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (between Phase 4 and Phase 5)
</deferred_reading>

<context>
$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 load --type spec --category arch` — load architecture constraints
3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
4. All optional — proceed without if unavailable (log warning)

### Role Knowledge
`maestro search --category debug` → select relevant → `maestro load --type knowhow --id`
</context>

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

<execution>
Follow '~/.maestro/workflows/analyze.md' completely.

### Evidence-Backed Decisions

Every decision MUST trace to independently gathered evidence. Manual Read/Grep is preparation — NOT evidence. Valid evidence sources:
- cli-explore-agent output (code anchors, call chains, data flows)
- maestro delegate CLI analysis output (multi-perspective findings)
- User-provided input (domain knowledge, constraints, corrections)

Decisions without CLI/agent-sourced evidence MUST be flagged as LOW CONFIDENCE.

### Boundary Grill (Step 5 → Step 6)

After discussion rounds, BEFORE synthesis: run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
Input: discussion.md decisions + exploration-codebase.json. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.

### Standard Mode Gates

Gates 1-4 are defined in `analyze.md`. NEVER skip gates. NEVER substitute manual Read/Grep for agent/CLI exploration.

### Artifact Verification

Before writing the completion report (Step 9), verify ALL expected artifacts exist in OUTPUT_DIR:
```
FULL_MODE_REQUIRED = [
  "discussion.md",             // Step 3+5
  "exploration-codebase.json", // Step 4.1
  "explorations.json" OR "perspectives.json", // Step 4.3
  "analysis.md",               // Step 6
  "conclusions.json",          // Step 7
  "context.md",                // Step 8
  "context-package.json"       // Step 8.6
]
```
If any artifact is missing: DO NOT report completion. Produce the missing artifact first.

### --gaps Mode

When `--gaps` is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard pipeline.