---
description: "Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time: up to 3 source-labeled answer candidates per row (evidence / repo / AI reasoned), chosen answer merged into the target section, doc updated in place with a changelog bump. Same locked decisions as /multi-agent:analysis. Use when an analysis document's open questions need answering before development starts."
description-tr: "Analiz v3 dokümanının Bölüm 20 Riskler ve Açık Sorular satırlarını tek tek çözer. Satır başına en fazla 3 kaynak-etiketli cevap adayı önerir (kanıttan / repodan / AI çıkarımı), seçilen cevabı ilgili gövde bölümüne işler ve dokümanı Bölüm 23 changelog artışıyla yerinde günceller. /multi-agent:analysis'in eşlikçisi - aynı Kilitli kararlar geçerli (alıntı disiplini, humanizer noktalama, MCP yok, otomatik commit yok). Platform bazlı dosya setleri için isteğe bağlı kardeş yayılımı."
argument-hint: "[path/to/analysis/<feature>-<platform>.md] [--autonomous]"
---

# multi-agent analysis-resolve - Open Question Resolver for Analysis Docs

Companion command to `/multi-agent:analysis`. Takes an `analysis/<feature>-<platform>.md` (template v3) and walks the user through the open rows of Section 20 (Riskler ve Acik Sorular / Risks and Open Questions) one row at a time, proposing source-labeled answer candidates and merging the chosen answer into the proper body section. The pattern follows a spec-resolver approach (walk the open rows, propose source-labeled answer candidates, merge the chosen answer) adapted to the analysis doc contract.

**Core invariant - read this twice:** the analysis doc is authoritative and forward-looking. The resolver never invents an answer; if no source produces a credible candidate, the only options offered are Defer and Other. Each Section 20 row is its own decision; never blend candidates across rows.

> **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix - instruction prose stays English. `AskUserQuestion.label` and `header` stay English; `question` and `description` follow `prefs.global.outputLanguage`. Fragments written INTO the doc follow the doc's own front-matter `language` field (not `outputLanguage`), so a `tr` doc stays uniformly Turkish even when the session language differs.

## Inherited Locked decisions (from /multi-agent:analysis - binding here)

- **Locked 3 (citation discipline).** A resolution that introduces a quoted UI string, endpoint path, error code, or analytics event name must carry a citation (`[Figma <nodeId>]`, `file:line`, `Confluence:<pageId>:<heading-slug>`). If the user's free-text Other answer quotes a string with no citation, ask one follow-up: `Where does this string come from?` with options `Repo file:line` / `Existing doc citation` / `Don't quote it`.
- **Locked 4 (forward-looking spec).** Repo-sourced answers that describe current/legacy behavior merge as `> Legacy reference: <text> (file:line)` blockquotes under the target entry, never as the lead sentence or a primary table row.
- **Locked 6 (no auto-commit).** The command rewrites the doc file(s) but never runs `git add` or `git commit`.
- **Locked 7 (humanizer punctuation).** Every fragment this command writes into the doc uses ASCII punctuation only: no em-dash (U+2014), en-dash (U+2013), ellipsis (U+2026), curly quotes, or section sign. Diacritics are preserved verbatim (Turkish letters stay as-is; never ASCII-fold prose). Run the verification grep from `analysis.md` Phase 3 step 3 after the final save.
- **Locked 24 (Pass B footnote).** When a resolution overrides a convention cell in Section 13 (or any per-platform projection), the cell's footnote is rewritten to `^[user-override: resolved via analysis-resolve <date>]`.
- **Locked 30 (no MCP outside analysis phase).** This command makes NO Figma MCP calls, no `api.figma.com` requests, no `figma.com/design/...` fetches. A row that genuinely needs new design information gets only `Defer` plus a printed recommendation to re-run `/multi-agent:analysis` for that input. Repo reads and `~/.claude/lib/extract-conventions.sh` re-runs are allowed (they are local evidence, not design fetches).

## Engine

The resolution engine - this command's own Locked decisions, the batched repo lookup, the sequential resolution loop and the finalize pass - lives in `$HOME/.claude/multi-agent-refs/analysis/resolve.md`. Pipeline Phase 4 (analysis mode) and Phase 2 (full pipeline) mount the same file, so there is one walk with three entry points.

Inherited decisions: `$HOME/.claude/multi-agent-refs/analysis/locked.md`.

## Input
- `$ARGUMENTS` - optional doc path. If empty, auto-glob at Phase 0.
- `--autonomous` - auto-pick the strongest candidate where exactly one source is credible; Defer otherwise. No per-row prompts; final report still printed.

## Steps

### Phase 0 - Intake

**Step 1 - Doc picker.** If `$ARGUMENTS` has a path, validate it. Otherwise glob `analysis/*-{ios,android,backend,frontend}.md` under cwd (and each repo root from `state.analysisSpec.repos[]` when the session still holds analysis state):
- 1 match: use it; echo the path, no question.
- 0 or 2+ matches: AskUserQuestion, `header: "Doc"`, question `<localized: "Which analysis document should we resolve?">`, options = matches (max 3) + Other for a free-typed path.

**Validate**: file exists; front-matter parses with `template_version: v3` (a `v2` doc gets `WARN: v2 doc has no resolvable Section 20 contract; re-run /multi-agent:analysis` and the run halts); a `## <n>. Riskler ve Acik Sorular` / `## <n>. Risks and Open Questions` heading exists (numbering may have re-flowed per the omission rule - match by title, not by the literal number 20).

**Step 2 - Repo root for "from repo" candidates.** Default order: front-matter platform's repo from `state.analysisSpec.repos[]` if the session holds it, else the repo containing the doc, else cwd. Confirm via AskUserQuestion only when no default resolves (`header: "Repo"`, options `Use current working directory` + Other).

**Step 3 - Mode.** Skipped when `--autonomous` was passed. AskUserQuestion, `header: "Mode"`, question `<localized: "Walk each question interactively, or run autonomously?">`, options:
- `Interactive (Recommended)` - one question at a time
- `Autonomous` - auto-pick where exactly one credible candidate exists, Defer otherwise

**Echo** one line: `Resolve: <doc> | repo: <path> | mode: <interactive|autonomous>. Parsing Section 20.`


## Reusable refs

| Path | Reason |
|------|--------|
| `$HOME/.claude/multi-agent-refs/analysis-template.md` | Section 20 / Section 23 table contracts, front-matter shape, omission re-flow |
| `$HOME/.claude/multi-agent-refs/conventions-defaults.md` | `convention-fallback` default values per platform |
| `~/.claude/lib/extract-conventions.sh` | fresh single-field extraction for convention-fallback candidates |
| `ai-common-toolkit:humanizer` | tone reference for longer merged fragments (short fragments only need the punctuation gate) |

## Notes

- This command is downstream-safe: it edits only the analysis doc, so the Locked 30 contract (analysis doc as the sole design source for Phase 2+) is strengthened, not weakened - dev phases consume a doc with fewer open holes.
- The resolver is idempotent over `Karar verildi / Decided` rows: re-running skips them.
- When the session no longer holds `state.analysisSpec`, everything still works: evidence candidates fall back to what the doc itself cites, and repo candidates come from the Phase 1 subagent.