var e=[{file:`SKILL.md`,content:`---
name: requirements-clarity
description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), involve cross-team coordination, or when the user says 'I want to build...', 'add a feature for...', 'implement...', 'create a system that...'. Ask two core questions first - Why? (YAGNI check) and Simpler? (KISS check) - then score 0-100 until clarity reaches 90+. Critical for preventing rework on underspecified features.
metadata:
  category: cross-cutting
  domain: general
  applicability: on-demand
  inputs: [requirements]
  outputs: [scored-requirements, clarifications]
  relatedSkills: [brainstorming]
---

# Requirements Clarity

## When to Skip

Do NOT activate when:
- Specific file paths mentioned (e.g., "auth.go:45")
- Code snippets or existing functions/classes referenced
- Bug fixes with clear reproduction steps
- Task is a single-file change with obvious scope

## Mindset

Requirements engineering is detective work, not stenography. Your job is NOT to write down what the user says - it's to uncover what they haven't said yet.

The user knows their PROBLEM but often conflates it with a specific SOLUTION. Separate these. The problem is the requirement; the solution is a design decision.

Before asking questions, mentally model:
- **Stakeholders** - Who else cares? Who gets paged at 2am? Who pays?
- **Failure modes** - What breaks? What's the blast radius? What's unrecoverable?
- **Boundaries** - What's explicitly OUT of scope? What's "phase 2"?

## Protocol

### 1. YAGNI/KISS Gate

Before ANY scoring, ask:
- **Why?** — Is this needed now? YAGNI check.
- **Simpler?** — Is there a simpler approach? KISS check.

If the answers show the feature is not needed now, should be deferred, or has a trivial solution, advise that directly instead of continuing to scoring.

### 2. Score (0-100)

Assess the requirement against this rubric:

| Category | Points | Criteria |
|----------|--------|----------|
| Functional Clarity | /30 | Clear inputs/outputs (10), user interaction defined (10), success criteria stated (10) |
| Technical Specificity | /25 | Tech stack mentioned (8), integration points (8), constraints specified (9) |
| Implementation Completeness | /25 | Edge cases (8), error handling (9), data validation (8) |
| Business Context | /20 | Problem statement (7), target users (7), success metrics (6) |

### Calibration Examples

**Functional Clarity 10/10:**
"User clicks Submit -> system validates email format (RFC 5322), checks uniqueness against users table, returns 201 with serialized user object (id, email, createdAt) or 422 with field-level errors array [{field, code, message}]"

**Functional Clarity 3/10:**
"User can sign up"

**Technical Specificity 9/9 (constraints):**
"Response time < 200ms p95 for all CRUD endpoints, PostgreSQL 16+, horizontal scaling via stateless workers behind ALB, no server-side sessions"

**Technical Specificity 2/9:**
"Should be fast and scalable"

**Edge Cases 8/8:**
"Empty input -> show inline validation before submit. Concurrent duplicate emails -> second request gets 409 Conflict. Network timeout -> client retries 3x with exponential backoff, then shows offline banner"

**Edge Cases 2/8:**
"Handle errors appropriately"

### Expert Probing Techniques

For each gap category, ask focused questions that reveal hidden requirements:

**For edge cases:** Ask about empty states, concurrent access, partial failures, permission boundaries, rate limits, timezone/locale behavior, offline/degraded mode, data migration from existing state.

**For error handling:** Ask "What happens when [external dependency] is down?", "What does the user see during a 30-second timeout?", "How does the system recover from partial writes?"

**For integration points:** Ask "Who calls this?", "What calls does this make?", "What happens if the downstream service changes its contract?", "Is there a circuit breaker?"

**For data validation:** Ask "What's the maximum size?", "What characters are allowed?", "What about Unicode/emoji?", "What happens with 0, null, negative numbers, MAX_INT?"

**For business context:** Ask "Who loses money if this breaks?", "What's the rollback plan?", "How will you know this is working in production?"

### 3. Iterate Until ≥ 90

For each clarification round:
1. Score the current requirement.
2. Identify the 2-3 highest-impact gaps.
3. Ask focused questions for one category at a time.
4. Update the score after each user response.
5. Capture clarified details in a working outline.
6. Repeat until the score is at least 90.

Prefer short, targeted questions over long questionnaires. Build on previous answers instead of repeating the whole requirement.

**HARD RULE:** Do not generate the requirements document with a score below 90.

## NEVER

- **NEVER accept vague acceptance criteria** like "it should work" or "user-friendly" - demand measurable outcomes (response time, error rate, specific user action -> specific system response)
- **NEVER skip the YAGNI check** - 40% of requirements are premature. Ask "what happens if we ship without this?" first
- **NEVER ask more than 3 questions per round** - cognitive overload causes shallow answers. Depth > breadth.
- **NEVER accept "edge cases: handle errors appropriately"** - this means "I haven't thought about it." Push for specific scenarios.
- **NEVER generate the document below score 90** - incomplete requirements cause more rework than taking time to clarify
- **NEVER repeat questions the user already answered** - build on previous responses, reference what they said
- **NEVER score above 80 without concrete acceptance criteria** - if you can't write a test for it, it's not a requirement

### 4. Generate Requirements Document

**Output path (flow-aware):**
- If a flow is active: \`flow({ action: 'status' })\` → write to \`{{artifacts_path}}/requirements.md\`
- If no flow active: write to \`.spec/{feature_name}/requirements.md\`

To detect active flow:
\`\`\`
const flowStatus = flow({ action: 'status' });
if (flowStatus.active) {
  // Output to: .flows/{topic}/.spec/requirements.md
  outputPath = \`\${flowStatus.artifactsPath}/requirements.md\`;
} else {
  outputPath = \`.spec/\${featureName}/requirements.md\`;
}
\`\`\`

Use \`create_file\` to save the document after the score reaches 90 or higher.

Required structure:
- **Requirements Description**
  - Background
  - Feature overview
  - Detailed requirements
  - Edge cases
- **Design Decisions**
  - Technical approach
  - Constraints
  - Risk assessment
- **Acceptance Criteria**
  - Functional acceptance checkboxes
  - Quality standards
  - User acceptance
- **Execution Phases**
  - Preparation
  - Core development
  - Integration and testing
  - Deployment

Each section must contain concrete, implementation-ready content. Do not leave placeholders.

Footer fields:
- Document Version
- Created timestamp
- Clarification Rounds count
- Quality Score /100

**After writing:** Also store a compact summary in flow-scoped knowledge for downstream step consumption:
\`\`\`
knowledge({ 
  action: "remember", 
  scope: "flow", 
  category: "context",
  title: "Requirements: <feature>",
  content: "Score: <X>/100\\nKey Requirements:\\n- <req1>\\n- <req2>\\nAcceptance Criteria:\\n- <criteria1>\\nConstraints:\\n- <constraint1>"
})
\`\`\`
This ensures downstream steps (Spec, Plan, Implementation) can access requirements via \`withdraw\` even without reading the file.
`}];export{e as default};