From rune
Elicits detailed requirements for new features via probing questions, stakeholder mapping, scope definition, and produces structured Requirements Document before planning or coding.
npx claudepluginhub rune-kit/rune --plugin @rune/analyticsThis skill uses the workspace's default tool permissions.
Business Analyst agent — the ROOT FIX for "Claude works a lot but produces nothing." BA forces deep understanding of WHAT to build before any code is written. It asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document.
Performs requirements analysis: decomposes problems, scans stakeholders, structures and prioritizes needs. Produces 1-requirements.md lifecycle doc before tech-spec. Not for task tickets or solutions.
Turns vague goals into structured requirements.md via systematic interview across business/user/tech axes, extraction, and cross-check. Outputs for /blueprint in greenfield/feature/refactor/bugfix formats.
Conducts structured business analysis for projects: problem/stakeholder analysis, as-is/to-be gap analysis, user personas, scope definition. Creates BA documents and manages GitHub issues/PRs/branches.
Share bugs, ideas, or general feedback.
Business Analyst agent — the ROOT FIX for "Claude works a lot but produces nothing." BA forces deep understanding of WHAT to build before any code is written. It asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document.
BA produces WHAT, not HOW. Never write code. Never plan implementation. Output is a Requirements Document → hand off to rune:plan for implementation planning.Wrong requirements shipped correctly is the most expensive bug. BA's job is to prevent it — measure clarity (Step 2.5), measure completeness (Step 3.5), and measure cross-dimension consistency (Step 3.6) before handoff.
cook Phase 1 when task is product-oriented (not a simple bug fix)scaffold Phase 1 before any project generation/rune ba <requirement> — manual invocationscout (L2): scan existing codebase for contextresearch (L3): look up similar products, APIs, integrationsplan (L2): hand off Requirements Document for implementation planningbrainstorm (L2): when multiple approaches exist for a requirementdesign (L2): when requirements include UI/UX components — hand off visual requirementscook (L1): before Phase 2 PLAN, when task is non-trivialscaffold (L1): Phase 1, before any project generationplan (L2): when plan receives vague requirementsmcp-builder (L2): requirements elicitation before MCP server design/rune ba direct invocationba → plan — ba produces requirements, plan produces implementation stepsba → brainstorm — ba calls brainstorm when multiple requirement approaches existba ↔ cook — cook calls ba for non-trivial tasks, ba feeds requirements into cook's pipelineba → scaffold — scaffold requires ba output before project generationRead the user's request. Classify the requirement type:
| Type | Signal | Depth |
|---|---|---|
| Feature Request | "add X", "build Y", "I want Z" | Full BA cycle (Steps 1-7) |
| Bug Fix | "broken", "error", "doesn't work" | Skip BA → direct to debug |
| Refactor | "clean up", "refactor", "restructure" | Light BA (Step 1 + Step 4 only) |
| Integration | "connect X to Y", "integrate with Z" | Full BA + API research |
| Greenfield | "new project", "build from scratch" | Full BA + market context |
If Bug Fix → skip BA, route to cook/debug directly. If Refactor → light version (Step 1 + Step 4 only). Skip Steps 2, 2.5, 3, 5, 6.
If existing codebase → invoke rune:scout for context before proceeding.
Before proceeding to elicitation, check whether the requirements are already in context. Re-asking what the user already told you is the second-most expensive bug.
Activate Synthesis Mode instead of standard elicitation if ANY of:
| Signal | Threshold |
|---|---|
| User pasted a spec / PRD / brief | > 200 words describing the feature |
| Conversation has > 1000 words on this feature | Sufficient context already gathered |
| User said "synthesize" / "I already explained" / "just write the spec" | Explicit synthesis request |
Continuation — .rune/features/<name>/requirements.md exists with prior answers | Re-elicitation would duplicate |
| Issue tracker has filled-in template (problem, story, acceptance criteria) | Source already structured |
In Synthesis Mode: extract answers from existing context, draft the Requirements Document with source citations for every section, then confirm rather than re-interview. Ask follow-ups ONLY on the 1-2 dimensions with genuine gaps. Skip steps 2, 2.5 if all 5 dimensions are filled or partial-but-acceptable.
Workflow detail + anti-patterns: references/synthesis-mode.md.
Before any elicitation, check whether the request matches a concept previously rejected.
Glob .out-of-scope/*.md — if directory absent, skip silently.concept, aliases).- and whitespace).confidence (0.0–1.0).Action by confidence:
| Confidence | Verdict | Action |
|---|---|---|
| ≥ 0.8 | exact-match | Surface to user: "This matches a prior rejection (.out-of-scope/<slug>.md) — closed because [body's "Why out of scope" first sentence]. Do you still feel the same way?" Pause for user response before continuing. |
| 0.5 – 0.79 | similar | Mention inline: "This is similar to a prior rejection (<slug>). Would you like to review it before we proceed?" Continue regardless of answer. |
| < 0.5 | no-match | Continue silently, no user-facing mention. |
Emit outofscope.match signal with {concept, confidence, verdict} so downstream skills (cook, plan) inherit the context.
If verdict is exact-match AND user says "yes I still want it" → record their override reason in the Requirements Document ## Risks section AND mark priority_to_revisit: high in the existing .out-of-scope/<slug>.md (do NOT delete the file). The override forces the candidate up the revisit ladder; it doesn't erase the prior decision.
If verdict is exact-match AND user accepts the prior rejection → end the BA session with a one-line summary referencing the file. No further questions.
Format reference: references/out-of-scope-format.md.
If the user explicitly rejects the feature at any point during elicitation (Steps 2-3) — common phrases: "scrap it", "actually nah, don't build this", "we won't do this", "kill the feature", "drop it" — STOP elicitation and write a .out-of-scope/<slug>.md record before ending the session.
Without this WRITE path, oral rejections vanish — the next session re-asks the same questions and the user has to re-reject. Step 1.5 (READ) only catches matches against existing files; Step 1.6 (WRITE) is what produces those files in the first place.
Mid-elicitation rejection MUST produce a `.out-of-scope/.md` file before session end. A rejection without a written record is a rejection that didn't happen.Procedure:
Confirm rejection is durable, not deferral. Ask one clarifier:
"Just to record this correctly: is this out of scope (project doesn't want this), or deferred (not now but maybe later)? Out-of-scope gets recorded so we don't re-litigate; deferred goes to backlog instead."
.out-of-scope/ write), end session with a one-line noteCapture the durable reason. Ask:
"What's the reason this is out of scope? (project scope, technical constraint, strategic decision — not a temporary circumstance)"
If the user gives a temporary reason ("we're busy"), reframe: "That's a deferral — should I route to backlog instead?"
Generate slug (kebab-case, ≤40 chars, recognizable without opening the file).
Lexical-similarity check: Glob .out-of-scope/*.md, parse each frontmatter's concept + aliases, compute overlap. If any existing concept has ≥0.7 overlap → APPEND to that file's prior_requests list and mark rejected_by: ba for this round. Do NOT create a duplicate.
Write the file using the format in references/out-of-scope-format.md:
concept, aliases, decision: rejected, rejected_at, rejected_by: ba, prior_requests, optional revisit_if)Emit outofscope.recorded signal carrying {slug, rejected_by: ba, prior_requests_count} so downstream skills know a new rejection landed.
End BA session with one-line summary:
"Recorded as out of scope in
.out-of-scope/<slug>.md. Future similar requests will surface this. Override anytime by editing the file."
When NOT to write:
.out-of-scope/prior_requests of the existing file (handled in Step 1.5 path)Before emitting ANY of the 5 elicitation questions, run the 4-item pre-check on each intended question:
package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml?README.md / CLAUDE.md / docs/?The gate is "tried to infer" — not "must succeed in inferring." If the file genuinely doesn't have the answer, the attempt itself is the gate.
Cache inferred answers in the requirements doc:
**Inferred from package.json**: TypeScript 5.4, Next.js 14.2, React 18.3
**Inferred from .github/workflows/**: CI runs on PRs targeting main
Worked examples + edge cases: references/explore-first.md.
Ask exactly 5 probing questions, ONE AT A TIME (not all at once):
Every question the user answers burns attention you don't get back. Protect it.
package.json, don't ask.README, don't ask.Every Q should earn its slot: removing it must leave the Requirements Document materially worse. If it wouldn't, cut the question.
Choose the framework that fits the requirement type. Use it to STRUCTURE the 5 Questions above, not replace them.
| Framework | When to Use | Structure |
|---|---|---|
| PICO | Clinical, research, data-driven, or A/B testing features | Population (who), Intervention (what change), Comparison (vs what), Outcome (measurable result) |
| INVEST | User stories for sprint-sized features | Independent, Negotiable, Valuable, Estimable, Small, Testable |
| Jobs-to-be-Done | Product features, user workflows | "When [situation], I want to [motivation] so I can [expected outcome]" |
PICO Example (data feature):
P: Dashboard users monitoring real-time metrics
I: Add anomaly detection alerts
C: vs. current manual threshold setting
O: 30% faster incident detection (measurable KPI)
When to apply which:
After each question round, compute an Ambiguity Score to determine if requirements are clear enough to proceed. This prevents premature handoff to plan with vague inputs.
Ambiguity = 1 - weighted_average(dimensions)
Dimensions (weights vary by requirement type):
Greenfield: Goal (40%) + Constraints (30%) + Success Criteria (30%)
Feature: Goal (30%) + Constraints (30%) + Success Criteria (20%) + Integration (20%)
Integration: Goal (20%) + Constraints (25%) + Success Criteria (20%) + API Contract (35%)
| Dimension | 0.0 (Unknown) | 0.5 (Partial) | 1.0 (Clear) |
|---|---|---|---|
| Goal | "Make it better" | "Improve dashboard performance" | "Dashboard loads in <2s with 10k rows" |
| Constraints | No constraints mentioned | "Use existing DB" | "PostgreSQL 15, no new deps, GDPR compliant" |
| Success Criteria | "It should work" | "Users can see their data" | "AC-1.1: GIVEN 10k rows WHEN page loads THEN render <2s" |
| Integration | "Connect to the API" | "Use REST, need auth" | "POST /api/v2/orders, OAuth2, rate limit 100/min" |
| API Contract | "It sends data somewhere" | "JSON payload to endpoint" | "OpenAPI spec provided, request/response schemas defined" |
| Ambiguity | Level | Action |
|---|---|---|
| < 15% | Crystal Clear | Proceed to Step 3 immediately |
| 15-25% | Acceptable | Proceed with noted assumptions — flag gaps in Requirements Doc |
| 25-40% | Unclear | Ask 1-2 targeted follow-up questions on weakest dimension |
| > 40% | Blocked | Do NOT proceed. Re-ask the weakest dimension question with examples |
After each of the 5 Questions (Step 2), update the score:
Round 1 (WHO): Goal ≈ 0.3, others = 0.0 → Ambiguity ≈ 91%
Round 2 (WHAT): Goal ≈ 0.7, Success ≈ 0.3 → Ambiguity ≈ 72%
Round 3 (WHY): Goal ≈ 0.9, Success ≈ 0.5 → Ambiguity ≈ 47%
Round 4 (BOUNDS): Constraints ≈ 0.6 → Ambiguity ≈ 30%
Round 5 (CONSTR): Constraints ≈ 0.9 → Ambiguity ≈ 12% ✅
If Ambiguity drops below 15% before all 5 questions are asked (e.g., user provides a detailed PRD), skip remaining questions and proceed. The gate is about clarity, not ceremony.
After completing Step 2, show the user:
Clarity Score: [100 - ambiguity]%
Goal: [██████████] 0.9
Constraints: [████████░░] 0.8
Success Criteria: [██████░░░░] 0.6 ← weakest
Status: ACCEPTABLE (ambiguity 23%) — proceeding with noted gaps
After elicitation, before hidden-requirement discovery, scan the user's answers for assertions about current behavior — phrasings like "the system X", "the code does X", "we already X", "right now it X".
For each such assertion:
Grep the codebase for evidence (function names, route handlers, schema definitions matching the asserted behavior).| Outcome | Action |
|---|---|
| Grep confirms claim | Proceed; record term in CONTEXT.md if domain-relevant |
| Grep contradicts claim | Surface the conflict immediately. "You said the system does X, but the code path I see does Y. Which is canonical?" Pause until resolved. |
| Grep returns nothing | Note as unverified; ask user for the file/function name; do not record in CONTEXT.md until verified |
This gate prevents the agent from silently transcribing user-asserted behavior that contradicts code — a common source of "the docs say X but the code does Y" drift.
After the 5 questions, analyze for requirements the user DIDN'T mention:
Technical hidden requirements:
Business hidden requirements:
Present discovered hidden requirements to user: "I found N additional requirements you may not have considered: [list]. Which are relevant?"
When presenting options, alternatives, or scope decisions to the user, rate each with a Completeness score (X/10):
| Score | Meaning | Guidance |
|---|---|---|
| 9-10 | Complete — all edge cases, full coverage, production-ready | Always recommend |
| 7-8 | Covers happy path, skips some edges | Acceptable for MVP |
| 4-6 | Shortcut — defers significant work to later | Flag trade-off explicitly |
| 1-3 | Minimal viable, technical debt guaranteed | Only for time-critical emergencies |
Always recommend the higher-completeness option unless the delta is truly expensive. With AI-assisted coding, the marginal cost of completeness is near-zero:
| Task Type | Human Team | AI-Assisted | Compression |
|---|---|---|---|
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
| Test writing | 1 day | 15 min | ~50x |
| Feature implementation | 1 week | 30 min | ~30x |
| Bug fix + regression test | 4 hours | 15 min | ~20x |
When showing effort estimates, always show both scales: (human: ~X / AI: ~Y). The compression ratio reframes "too expensive" into "15 minutes more."
Anti-pattern: "Choose B — it covers 90% of the value with less code." → If A is only 70 lines more, choose A. The last 10% is where production bugs hide.
After ambiguity + completeness pass, scan for cross-dimension contradictions. Ambiguity measures CLARITY of each dimension in isolation; this step measures CONSISTENCY across dimensions. A perfectly clear requirement can still contradict itself.
Run each, label verdict 🟢 pass / 🟡 warn / 🔴 fail:
| # | Check | 🔴 Fail | 🟢 Pass |
|---|---|---|---|
| 1 | Every Acceptance Criterion traces to a User Story | AC orphaned | 1:N mapping clear |
| 2 | Every Business Rule (Q5) is enforced in an AC or Exception Flow | Rule has no enforcement path | Rule → specific AC or exception |
| 3 | Scope IN ∩ Scope OUT = ∅ | Direct overlap in phrasing | Sets disjoint |
| 4 | Every user-story flow has a terminal state | State loop without exit condition | Terminal state explicit |
| 5 | Dependencies (Step 4) ⊂ Constraints acknowledged (Q5) | Dependency never mentioned in constraints | All deps covered |
| 6 | NFRs measurable against at least one AC | NFR has no test hook | Every NFR → testable AC |
| 7 | Hidden requirements (Step 3) resolved in/out | Silent inclusion | User confirmed inclusion or exclusion |
| 0 | Prior rejection check (Step 1.5) — exact-match resolved with explicit override or session ended | Silent re-litigation of rejected concept | User chose: override (priority bumped) OR accept prior decision (session ends) |
Logic Consistency Report:
1. AC → User Story: 🟢 all AC trace to US-1 or US-2
2. Business rule → AC: 🟡 "no duplicate emails" cited — exception flow missing
3. Scope disjoint: 🟢
4. Terminal states: 🟢
5. Deps in constraints: 🔴 "PostgreSQL 15" missing from Q5 answer
6. NFR measurable: 🟢
7. Hidden reqs resolved: 🟢
Verdict: 1 🔴, 1 🟡, 5 🟢 → BLOCK handoff until 🔴 fixed
| Result | Action |
|---|---|
| 0 🔴 | Proceed to Step 4 — 🟡 warnings become "Risks" in Requirements Doc |
| 1-2 🔴 | BLOCK — ask targeted question or re-scope to resolve each 🔴 |
| 3+ 🔴 | Scrap Steps 2-3 and restart — requirements structurally incoherent |
Based on all gathered information, produce:
In-Scope (explicitly included):
Out-of-Scope (explicitly excluded):
Assumptions (things we're assuming without proof):
Dependencies (things that must exist before we can build):
For each in-scope feature, generate:
US-1: As a [persona], I want to [action] so that [benefit]
AC-1.1: GIVEN [context] WHEN [action] THEN [result]
AC-1.2: GIVEN [error case] WHEN [action] THEN [error handling]
AC-1.3: GIVEN [edge case] WHEN [action] THEN [graceful behavior]
Rules:
Assess and document ONLY relevant NFRs:
| NFR | Requirement | Measurement |
|---|---|---|
| Performance | Page load < Xs, API response < Yms | Lighthouse, k6 |
| Security | Auth required, input validation, OWASP top 10 | sentinel scan |
| Scalability | Expected users, data volume | Load test target |
| Reliability | Uptime target, error budget | Monitoring threshold |
| Accessibility | WCAG 2.2 AA | Axe audit |
Only include NFRs relevant to this specific task. Don't generate a generic checklist.
For product-oriented requirements (Feature Request, Integration, Greenfield), generate tiered strategic recommendations. This structures the path forward into actionable time horizons.
Three Tiers:
| Tier | Timeframe | Focus | Characteristics |
|---|---|---|---|
| Quick Win | 0-30 days | Immediate impact | Low effort, high visibility, builds momentum |
| Differentiation | 1-3 months | Competitive edge | Medium effort, unique value, hard to copy |
| Long-term Moat | 6-12 months | Sustainable advantage | High effort, defensible, compounds over time |
For each tier, specify:
### Quick Win (0-30 days)
- **Action**: [Specific deliverable]
- **Resources**: [Team size, tools, dependencies]
- **Expected Impact**: [Measurable outcome]
- **Risk if skipped**: [What happens without this]
### Differentiation (1-3 months)
- **Action**: [...]
- **Resources**: [...]
- **Expected Impact**: [...]
- **Risk if skipped**: [...]
### Long-term Moat (6-12 months)
- **Action**: [...]
- **Resources**: [...]
- **Expected Impact**: [...]
- **Risk if skipped**: [...]
Rules:
Produce three structured artifacts — not one prose doc. Plan consumes all three; each answers a different question.
| Artifact | Question Answered | Consumer |
|---|---|---|
requirements.md | WHAT to build and WHY | plan, cook |
requirements.mermaid | WHAT does the flow look like visually | plan, design, review |
tasks.md | WHAT work layers exist | plan (as task backbone, not from scratch) |
Structured document combining Steps 1-6.5. Save to .rune/features/<feature-name>/requirements.md:
# Requirements Document: [Feature Name]
Created: [date] | BA Session: [summary]
## Context
[Problem statement — 2-3 sentences]
## Stakeholders
- Primary user: [who]
- Affected systems: [what]
## User Stories
[from Step 5]
## Scope
### In Scope
### Out of Scope
### Assumptions
## Non-Functional Requirements
[from Step 6]
## Dependencies
[from Step 4]
## Risks
- [risk]: [mitigation]
## Strategic Recommendations
[from Step 6.5 — skip for Bug Fix/Refactor]
## Logic Consistency Report
[from Step 3.6 — verbatim, for audit trail]
## Next Step
→ Hand off to rune:plan (consumes all 3 artifacts)
Auto-generate from User Stories. Save to .rune/features/<feature-name>/requirements.mermaid.
Sequence diagram (primary happy path from US-1):
sequenceDiagram
actor User
participant System
participant Database
User->>System: [action from US-1]
System->>Database: [read/write from AC-1.1]
Database-->>System: [response]
System-->>User: [result from AC-1.1]
State machine (only if any User Story implies state):
stateDiagram-v2
[*] --> initial
initial --> processing: [trigger from AC]
processing --> success: [happy path AC]
processing --> failed: [error AC]
success --> [*]
failed --> initial: retry
Skip state machine if feature is stateless (simple CRUD with no lifecycle). Sequence is always produced.
Pre-broken implementation tasks by layer. Plan refines this backbone, does not create from scratch. Save to .rune/features/<feature-name>/tasks.md:
# Implementation Tasks: [Feature Name]
## Data Layer
- [ ] Schema — [tables/models from AC]
- [ ] Migration up + down
- [ ] Seed/fixtures if tests need them
## Logic Layer
- [ ] [each Q5 Business Rule → one task]
- [ ] Validation for [each AC error case]
- [ ] State transitions from requirements.mermaid (if present)
## Interface Layer (API / UI)
- [ ] [each User Story → one endpoint or UI component]
- [ ] Contract schema from AC (request/response)
- [ ] Error handling for [each AC error]
## Test Layer
- [ ] Unit: [each business rule → one test]
- [ ] Integration: [each AC happy path]
- [ ] Regression: [each AC error case]
## NFR Verification
- [ ] [each NFR from Step 6 → one measurement task]
Derivation rules:
Emit signal to plan with paths to all three artifacts. Plan MUST read all three before producing phase files — the triad is the contract.
After the artifact triad is saved, append/update the project glossary CONTEXT.md with any domain terms that were sharpened during this session.
CONTEXT-MAP.md exists at root → multi-context; pick the right per-context CONTEXT.mdCONTEXT.md exists → use itCONTEXT.md lazilyConflict gate — if a new term has ≥0.7 token overlap with an existing one, surface to user (merge / rename / keep distinct). NEVER silently re-define an existing term.
Format reference: references/context-md-format.md.
Triad of artifacts under .rune/features/<feature-name>/:
| File | Template Reference |
|---|---|
requirements.md | Step 7 Artifact 1 |
requirements.mermaid | Step 7 Artifact 2 (sequence + optional state machine) |
tasks.md | Step 7 Artifact 3 (Data / Logic / Interface / Test / NFR layers) |
Inside requirements.md the Decision Classification table MUST appear verbatim — plan gates on Decision compliance, Discretion items skip approval:
| Category | Meaning | Example |
|---|---|---|
| Decisions (locked) | User confirmed — agent MUST follow | "Use PostgreSQL, not MongoDB" |
| Discretion (agent decides) | User trusts agent judgment | "Pick the best validation library" |
| Deferred (out of scope) | Explicitly NOT this task | "Mobile app — future phase" |
| Artifact | Format | Location |
|---|---|---|
| Requirements document | Markdown | .rune/features/<feature-name>/requirements.md |
| Visual model | Mermaid (sequence + optional state machine) | .rune/features/<feature-name>/requirements.mermaid |
| Implementation task backbone | Markdown checklist by layer | .rune/features/<feature-name>/tasks.md |
| Logic Consistency Report | Markdown section | Embedded in requirements.md |
| Ambiguity + Completeness scores | Markdown display blocks | Embedded in requirements.md |
Known failure modes for this skill. Check these before declaring done.
| Failure Mode | Severity | Mitigation |
|---|---|---|
| Skipping questions because "requirements are obvious" | CRITICAL | HARD-GATE: 5 questions mandatory, even for "simple" tasks |
| Answering own questions instead of asking user | HIGH | Questions require USER input — BA doesn't guess |
| Producing implementation details (HOW) instead of requirements (WHAT) | HIGH | BA outputs requirements doc → plan outputs implementation |
| All-at-once question dump (asking 5 questions in one message) | MEDIUM | One question at a time, wait for answer before next |
| Asking open-ended questions when yes/no or multiple-choice would work | HIGH | Question Discipline rule 2 — option sets are faster to answer and easier to cache |
| Asking for info already in the repo/message (stack, framework, audience) | HIGH | Question Discipline rule 3 — read package.json/README/config first, ask only what you genuinely can't find |
| Exceeding 5 questions when the user seems "engaged" | MEDIUM | Question Discipline rule 1 — hard cap at 5. A 6th question is a sign of stalling, not thoroughness |
| Re-asking on session restart when answers were cached | MEDIUM | Question Discipline rule 4 — load .rune/features/<name>/requirements.md and reuse cached Q→A pairs |
| Missing hidden requirements (auth, error handling, edge cases) | HIGH | Step 3 checklist is mandatory scan |
| Requirements doc too verbose (>500 lines) | MEDIUM | Max 200 lines — concise, actionable, testable |
| Skipping BA for "simple" features that turn out complex | HIGH | Let cook's complexity detection trigger BA, not user judgment |
| Recommending shortcuts without Completeness Score | MEDIUM | Step 3.5: every option needs X/10 score + dual effort estimate (human vs AI). "90% coverage" is a red flag when 100% costs 15 min more |
| Handing off to plan with ambiguity > 40% | CRITICAL | Step 2.5 HARD-GATE: compute ambiguity score after elicitation, block handoff if > 40%, ask targeted follow-up on weakest dimension |
| Skipping ambiguity scoring because "user seems clear" | HIGH | Always compute the score — perceived clarity ≠ measured clarity. The formula catches gaps humans miss |
| Tiered recommendations too vague ("improve things") | MEDIUM | Each tier needs specific Action + measurable Expected Impact. "Build better UX" → "Reduce checkout steps from 5 to 3, targeting 15% conversion lift" |
| All three tiers have same resources/effort | MEDIUM | Quick Win should be low-effort. If all tiers need "2 engineers, 3 months" → re-scope Quick Win to something achievable in 1 sprint |
| Skipping Logic Consistency check because ambiguity is low | CRITICAL | Step 3.6 HARD-GATE: clarity ≠ consistency. A 90% clarity spec can still contain pairwise contradictions (scope IN/OUT overlap, rules with no enforcement, orphan ACs) |
| Handing off to plan with unresolved 🔴 consistency fails | CRITICAL | Step 3.6 gate: 1+ 🔴 = BLOCK. 🟡 allowed only when logged as Risk in requirements.md |
| Producing only requirements.md, skipping mermaid and tasks.md | HIGH | Step 7 is a triad — plan's contract expects all 3. Sequence diagram is always produced; state machine only if stateful; tasks.md always produced |
| Mermaid diagram unrelated to actual user stories (decorative only) | MEDIUM | Sequence must trace AC-1.1 of US-1; state machine nodes must map to state-bearing ACs. Auditable by pattern-match |
| tasks.md as flat list instead of layered | MEDIUM | Derivation rules enforce 1 US → Interface task, 1 rule → Logic + Unit test, 1 AC → Test task, 1 NFR → verification. Skipping layers loses plan's backbone structure |
| Re-litigating a previously rejected concept without surfacing it | HIGH | Step 1.5 HARD-GATE: scan .out-of-scope/ first; exact match (≥0.8) MUST be surfaced before elicitation begins |
Skipping Step 1.5 because .out-of-scope/ directory looks empty | MEDIUM | Empty directory is silent-skip OK; directory absent entirely is silent-skip OK; never skip due to "I don't think this matches anything" — let the matcher decide |
| User asserts behavior; agent records user's version without grep verification | HIGH | Step 2.6 HARD-GATE: every "the system does X" assertion gets grep'd; conflicts surface to user before recording |
| Silently re-defining an existing CONTEXT.md term | HIGH | Step 7.5 conflict gate: ≥0.7 overlap → user chooses merge/rename/keep-distinct |
| Auto-creating an empty CONTEXT.md when no terms emerged | LOW | Lazy creation rule: only write when there's a non-trivial term to record |
Mid-elicitation rejection ("scrap it") that ends the session without writing .out-of-scope/ | CRITICAL | Step 1.6 HARD-GATE: explicit rejection MUST produce .out-of-scope/<slug>.md before session end — oral rejections vanish, force re-litigation next session |
Writing .out-of-scope/ for a deferral instead of routing to backlog | MEDIUM | Step 1.6 procedure step 1: confirm "out of scope" vs "deferred" — temporary reasons go to backlog, not the rejection KB |
| Running 5-question elicitation when conversation already contains rich context | HIGH | Step 1.4: synthesis-trigger check fires before Step 2 — pasted spec / >1000 words / continuation / explicit "synthesize" → switch to Synthesis Mode (extract + cite + confirm), don't re-interview |
| Synthesizing requirements without source citations | HIGH | Synthesis Mode requires citing source for every dimension (user message N, pasted doc, continuation file). User cannot verify interpretation without citations |
| Auto-handoff to plan after synthesis without explicit user "go"/"locked" confirmation | HIGH | Synthesis is interpretation, not transcription. Without explicit confirmation, drift becomes a downstream bug |
| Asking inferable questions ("what stack are you using?") without first checking package.json | HIGH | Step 2.0 HARD-GATE — every question requires prior tool-call evidence (Read/Glob/Grep) or explicit unavailability declaration |
| Re-asking a question already answered earlier in the conversation | MEDIUM | Step 2.0 check 4 — cache and reuse, never re-ask |
requirements.md + requirements.mermaid + tasks.mdplan for implementation planning~3000-6000 tokens input, ~1500-3000 tokens output. Opus for deep requirement analysis — understanding WHAT to build is the most expensive mistake to get wrong.