Ba

ba

Purpose

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.

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

BA produces WHAT, not HOW. Never write code. Never plan implementation. Output is a Requirements Document → hand off to rune:plan for implementation planning.

Triggers

• Called by cook Phase 1 when task is product-oriented (not a simple bug fix)
• Called by scaffold Phase 1 before any project generation
• /rune ba — manual invocation
• Auto-trigger: when user description is > 50 words OR contains business terms (users, revenue, workflow, integration)

Calls (outbound)

• scout (L2): scan existing codebase for context
• research (L3): look up similar products, APIs, integrations
• plan (L2): hand off Requirements Document for implementation planning
• brainstorm (L2): when multiple approaches exist for a requirement
• design (L2): when requirements include UI/UX components — hand off visual requirements

Called By (inbound)

• cook (L1): before Phase 2 PLAN, when task is non-trivial
• scaffold (L1): Phase 1, before any project generation
• plan (L2): when plan receives vague requirements
• mcp-builder (L2): requirements elicitation before MCP server design
• User: /rune ba direct invocation

Cross-Hub Connections

• ba → plan — ba produces requirements, plan produces implementation steps
• ba → brainstorm — ba calls brainstorm when multiple requirement approaches exist
• ba ↔ cook — cook calls ba for non-trivial tasks, ba feeds requirements into cook's pipeline
• ba → scaffold — scaffold requires ba output before project generation

Executable Steps

Step 1 — Intake & Classify

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

Step 1.4 — Synthesis Trigger Check

1000 words discussion, continuation session, filled issue template)"/>

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//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](references/synthesis-mode.md).

Step 1.5 — Out-of-Scope Match Check (READ)

Before any elicitation, check whether the request matches a concept previously rejected.

1. Glob .out-of-scope/*.md — if directory absent, skip silently.
2. For each file, parse YAML frontmatter (concept, aliases).
3. Build a token map (lowercased, split on - and whitespace).
4. Tokenize the user's request the same way.
5. Compute lexical overlap per concept; keep the top match's 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/.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 (`). Would you like to review it before we proceed?"* Continue regardless of answer. | | .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](references/out-of-scope-format.md).

Step 1.6 — Mid-Elicitation Reject WRITE Path

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/.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:

1. 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."

• If deferred → route to backlog (no .out-of-scope/ write), end session with a one-line note
• If out-of-scope → continue to step 2

1. Capture 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?"

1. Generate slug (kebab-case, ≤40 chars, recognizable without opening the file).

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

1. Write the file using the format in [references/out-of-scope-format.md](references/out-of-scope-format.md):

• YAML frontmatter (concept, aliases, decision: rejected, rejected_at, rejected_by: ba, prior_requests, optional revisit_if)
• Markdown body: concept name, "Why out of scope" (substantive reasoning from step 2), "What would change our mind" (if user volunteered signals)

1. Emit outofscope.recorded signal carrying {slug, rejected_by: ba, prior_requests_count} so downstream skills know a new rejection landed.

1. End BA session with one-line summary:

> "Recorded as out of scope in .out-of-scope/.md. Future similar requests will surface this. Override anytime by editing the file."

When NOT to write:

• User merely defers ("not now") → backlog, not .out-of-scope/
• User rejects a single requirement within a larger feature → adjust requirements doc Boundaries section, don't write a whole rejection file (the feature is still in scope)
• Bug rejections (already fixed, not reproducible) → not BA's job; route to incident or close the issue
• The match was already exact (≥0.8) and Step 1.5 surfaced it — user accepting the prior rejection just appends to prior_requests of the existing file (handled in Step 1.5 path)

Step 2.0 — Explore-First Pre-Check (HARD-GATE)

Before emitting ANY of the 5 elicitation questions, run the 4-item pre-check on each intended question:

1. Is the answer in package.json / pyproject.toml / Cargo.toml / go.mod / pom.xml?
2. Is the answer in README.md / CLAUDE.md / docs/?
3. Is it inferable from file extensions, directory structure, or config files?
4. Has the user answered it earlier in this conversation?

For every question Q the agent intends to ask, there MUST be prior tool-call evidence in the same session:

• At least 1 Read / Glob / Grep related to Q's domain, OR
• Explicit declaration: "Q cannot be answered from project artifacts because [specific reason]."

Without one of these, Q is BLOCKED — re-route to inference.

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](references/explore-first.md).

Step 2 — Requirement Elicitation (the "5 Questions")

Ask exactly 5 probing questions, ONE AT A TIME (not all at once):

1. WHO — "Who is the end user? What's their technical level? What are they doing right before and after using this feature?"
2. WHAT — "What specific outcome do they need? What does 'done' look like from the user's perspective?"
3. WHY — "Why do they need this? What problem does this solve? What happens if we don't build it?"
4. BOUNDARIES — "What should this NOT do? What's explicitly out of scope?"
5. CONSTRAINTS — "Any technical constraints? (existing APIs, performance requirements, security needs, deadlines)"

Do NOT skip questions. Do NOT answer your own questions. If user says "just build it" → respond with: "I'll build it better with 2 minutes of context. Question 1: [WHO]" Each question must be asked separately, wait for answer before next. Exception: if user provides a detailed spec/PRD → extract answers from it, confirm with user.

Question Discipline (MANDATORY)

Every question the user answers burns attention you don't get back. Protect it.

1. Max 5 questions total across the whole BA session. If you find yourself wanting a 6th, the answer is in the first 5 or you're stalling — re-read, don't re-ask.
2. Prefer yes/no or multiple-choice over open-ended. An open-ended question is a last resort when no reasonable option set exists.

• BAD: "What auth strategy do you want?"
• GOOD: "Auth: (a) email+password with JWT, (b) OAuth (Google/GitHub), (c) magic link, (d) I'll decide — pick one."

1. Never ask what you can infer. If the answer is in the repo, the user's message, or the classification from Step 1 — don't ask it.

• Wrong stack? → read package.json, don't ask.
• Wrong audience? → check the README, don't ask.
• Wrong framework? → check config files, don't ask.

1. Cache the answer. Write each Q→A pair into the Requirements Document verbatim. If the user restarts the BA session on the same feature, reuse the cached answers — never re-ask what was already answered.
2. Bundle yes/no questions after Q1 if the user is concise. A user who replies "y" / "n" / "skip" in 1-2 words tolerates a bundle. A user who replies with paragraphs wants the slow pace — keep one-at-a-time.

Every Q should earn its slot: removing it must leave the Requirements Document materially worse. If it wouldn't, cut the question.

Structured Elicitation Frameworks

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:

• Feature Request → INVEST (ensures stories are sprint-ready)
• Data/Analytics/Research feature → PICO (forces measurable outcome definition)
• Product/UX feature → Jobs-to-be-Done (keeps focus on user motivation)
• Integration → 5 Questions only (frameworks add noise for plumbing tasks)

Step 2.5 — Ambiguity Scoring (Execution Gate)

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.

Scoring Formula

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 Scoring (0.0 – 1.0)

| Dimension | 0.0 (Unknown) | 0.5 (Partial) | 1.0 (Clear) | |-----------|---------------|----------------|--------------| | Goal | "Make it better" | "Improve dashboard performance" | "Dashboard loads in 40%** | Blocked | Do NOT proceed. Re-ask the weakest dimension question with examples |

NEVER hand off to plan with Ambiguity > 40%. If user insists "just build it" at > 40%, respond: "Ambiguity is [X]% — the weakest area is [dimension]. One more answer cuts this in half: [targeted question]"

Scoring After Each Question

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.

Display Format

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

Step 2.6 — CONTEXT.md Cross-Reference Gate

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:

1. Grep the codebase for evidence (function names, route handlers, schema definitions matching the asserted behavior).
2. Compare grep results to the user's claim.

| Outcome

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Rune-kit
• Source: Rune-kit/rune
• License: MIT

Install and usage instructions live in the source repository linked above.