This skill operates in two modes:
- Local mode (invoked via
/analyze-spec in Claude Code): Full interactive Socratic interview — one question at a time, iterative refinement with the spec author.
- Remote mode (triggered externally via the
claude-spec-review-request label): Single-pass analysis — all questions posted at once as a single PR comment. Reads prior PR comments as context to account for already-answered questions.
Adapted from the Ouroboros-inspired deep interview methodology — specification quality is the primary bottleneck in AI-assisted development.
When in doubt, default to local mode (interactive).
Phase 1: Initialize
- Locate the spec:
- If a path is provided in
{{ARGUMENTS}}, use that directly.
- Otherwise, detect the PR number:
- Run
gh pr view --json number --jq .number to get the current branch's PR number.
- If that fails, list specs:
ls specs/ and ask the user which one.
- Look for
specs/<PR#>-*.md matching the PR number. This is the spec for this PR.
- If no match, fall back to finding any
specs/*.md file that is NOT TEMPLATE.md.
- If multiple specs match, prefer the one matching the PR number. If still ambiguous, ask the user.
- Read the spec thoroughly — understand all sections (Summary, Intent, Evaluation, Design, Execution).
- Read
jolt-eval/README.md so you understand the invariant/objective framework for scoring Success Criteria and generating questions.
- Explore the codebase: Run
explore agent to map codebase areas relevant to the spec's intent.
- Read prior context (remote mode): Read all existing PR comments via
gh pr view --json comments to identify questions already asked and answers already given. Account for these when scoring — don't re-ask answered questions.
Phase 2: Analyze
Score clarity across four dimensions (0.0–1.0 each):
| Dimension |
Weight |
What to assess |
| Goal Clarity |
0.35 |
Is the primary objective unambiguous? Can you state it in one sentence? Are key entities and relationships clear? |
| Constraint Clarity |
0.20 |
Are boundaries, limitations, and non-goals clear? |
| Success Criteria |
0.30 |
Could you write a test that verifies success? Are acceptance criteria concrete? Are relevant jolt-eval invariants/objectives described? |
| Context Clarity |
0.15 |
Do we understand the existing system well enough to modify it safely? |
Calculate ambiguity:
ambiguity = 1 - (goal × 0.35 + constraints × 0.20 + criteria × 0.30 + context × 0.15)
For each dimension below 0.9, generate a targeted question that would improve it:
- Questions should expose ASSUMPTIONS, not gather feature lists
- If the scope is conceptually fuzzy, ask an ontology-style question about what the thing fundamentally IS
- Cite specific codebase context (files, types, patterns) when relevant
Phase 3: Output (mode-dependent)
- Remote mode: single-pass PR comment with all findings — follow
references/remote-mode.md (in this skill's directory) for the comment template and label handling.
- Local mode: interactive Socratic interview — follow
references/local-mode.md for the round protocol, challenge modes, and stop conditions.
Task: Analyze the spec. {{ARGUMENTS}}
1---2name: analyze-spec3description: Spec analysis with ambiguity scoring — interactive locally, single-pass remotely via label4---56<Purpose>7Analyze a spec file using mathematical ambiguity scoring. The goal: ensure the spec is clear enough for a one-shot implementation with zero clarifying questions.89This skill operates in two modes:10- **Local mode** (invoked via `/analyze-spec` in Claude Code): Full interactive Socratic interview — one question at a time, iterative refinement with the spec author.11- **Remote mode** (triggered externally via the `claude-spec-review-request` label): Single-pass analysis — all questions posted at once as a single PR comment. Reads prior PR comments as context to account for already-answered questions.1213Adapted from the Ouroboros-inspired deep interview methodology — specification quality is the primary bottleneck in AI-assisted development.14</Purpose>1516<Execution_Policy>17- Gather codebase facts via `explore` agent BEFORE asking about them18- Cite repo evidence (file path, symbol, or pattern) instead of asking the spec author to rediscover it19- Score ambiguity transparently20- Do not approve until ambiguity ≤ threshold (default 0.2)21- Allow early approval with a clear warning if ambiguity is still high22</Execution_Policy>2324<Mode_Detection>25Detect which mode to use:26- **Remote mode**: Running in a remote Claude instance triggered by the `claude-spec-review-request` label. Indicators: environment is non-interactive (no TTY), or running inside a GitHub PR context.27- **Local mode**: Running interactively in a terminal via `/analyze-spec`.2829When in doubt, default to local mode (interactive).30</Mode_Detection>3132<Steps>3334## Phase 1: Initialize35361. **Locate the spec**:37 - If a path is provided in `{{ARGUMENTS}}`, use that directly.38 - Otherwise, detect the PR number:39 - Run `gh pr view --json number --jq .number` to get the current branch's PR number.40 - If that fails, list specs: `ls specs/` and ask the user which one.41 - Look for `specs/<PR#>-*.md` matching the PR number. This is the spec for this PR.42 - If no match, fall back to finding any `specs/*.md` file that is NOT `TEMPLATE.md`.43 - If multiple specs match, prefer the one matching the PR number. If still ambiguous, ask the user.442. **Read the spec** thoroughly — understand all sections (Summary, Intent, Evaluation, Design, Execution).453. **Read `jolt-eval/README.md`** so you understand the invariant/objective framework for scoring Success Criteria and generating questions.464. **Explore the codebase**: Run `explore` agent to map codebase areas relevant to the spec's intent.475. **Read prior context (remote mode)**: Read all existing PR comments via `gh pr view --json comments` to identify questions already asked and answers already given. Account for these when scoring — don't re-ask answered questions.4849## Phase 2: Analyze5051Score clarity across four dimensions (0.0–1.0 each):5253| Dimension | Weight | What to assess |54|-----------|--------|---------------|55| Goal Clarity | 0.35 | Is the primary objective unambiguous? Can you state it in one sentence? Are key entities and relationships clear? |56| Constraint Clarity | 0.20 | Are boundaries, limitations, and non-goals clear? |57| Success Criteria | 0.30 | Could you write a test that verifies success? Are acceptance criteria concrete? Are relevant `jolt-eval` invariants/objectives described? |58| Context Clarity | 0.15 | Do we understand the existing system well enough to modify it safely? |5960**Calculate ambiguity:**61`ambiguity = 1 - (goal × 0.35 + constraints × 0.20 + criteria × 0.30 + context × 0.15)`6263For each dimension below 0.9, generate a targeted question that would improve it:64- Questions should expose ASSUMPTIONS, not gather feature lists65- If the scope is conceptually fuzzy, ask an ontology-style question about what the thing fundamentally IS66- Cite specific codebase context (files, types, patterns) when relevant6768## Phase 3: Output (mode-dependent)6970- **Remote mode**: single-pass PR comment with all findings — follow `references/remote-mode.md` (in this skill's directory) for the comment template and label handling.71- **Local mode**: interactive Socratic interview — follow `references/local-mode.md` for the round protocol, challenge modes, and stop conditions.7273</Steps>7475<Examples>76<Good>77Probing jolt-eval coverage:78```79The Intent → Invariants section says "streaming must produce the same80commitments as the non-streaming path." That looks like a binary property —81have you considered capturing it as a new `jolt-eval` invariant? The existing82`split_eq_bind_low_high` in `jolt-eval/src/invariant/` is a close model83(reference vs. optimized implementation comparison). If this is out of scope,84the Invariants section should say so explicitly.85```86Why good: Names a concrete existing invariant as a model, leaves the N/A87door open, doesn't force a fit.88</Good>8990<Good>91Citing codebase context:92```93I found that `DoryCommitmentScheme` in `crates/jolt-prover-legacy/src/poly/commitment/dory/`94uses a two-tier structure (tier-1 chunks → tier-2 aggregation). The spec mentions95"streaming commitments" but doesn't specify which tier is streamed. Is this streaming96at tier-1 (chunk-level), tier-2 (aggregation), or both?97```98Why good: Explored first, cited specific types and files.99</Good>100</Examples>101102Task: Analyze the spec. {{ARGUMENTS}}
a16z