Agent skill

dev-buddy-requirements

Gather requirements with TDD test plans, pessimistic impact analysis, and risk registry. Appends Requirements, TDD Test Plan, and Risk Registry sections to the plan file.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/dev-buddy-requirements

SKILL.md

Requirements Stage Skill

Gather requirements, generate TDD test plans, and identify risks through pessimistic-first analysis. All output is appended to the plan file — no separate artifact files.


Step 1: Load Config and Resolve Executors

bash
bun -e "
import { loadDevBuddyConfig, getProviderType } from '${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-config.ts';
const config = loadDevBuddyConfig();
const stage = config.stages['requirements'];
const executors = stage.executors.map(exec => ({
  ...exec,
  providerType: getProviderType(exec.preset)
}));
console.log(JSON.stringify({ executors }));
"

Step 2: Resolve Session Variables

  1. Resolve tmpdir:

    bash
    bun -e "console.log(require('os').tmpdir())"
    

    Store as {TMPDIR}.

  2. Generate unique output ID:

    bash
    bun -e "console.log(require('crypto').randomBytes(4).toString('hex'))"
    

    Store as {RAND}. Output file for executor at index {i}: {TMPDIR}/.vcp/oneshot/req-{RAND}-{i}.json

  3. Ensure output directory:

    bash
    mkdir -p "{TMPDIR}/.vcp/oneshot"
    

Step 3: Check for RCA Context

Read the plan file. If it contains a ## RCA Diagnosis section, this is a bug-fix requirements stage. Extract the root cause summary, affected files, and fix constraints to include as context for the requirements executor.


Step 4: Prompt Assembly

For each requirements executor, construct the task prompt:

ORIGINAL REQUEST: {user's original request from conversation}
{If RCA context: "BUG-FIX CONTEXT — RCA Diagnosis from plan file:\nRoot Cause: {summary}\nRoot File: {file}:{line}\nFix Constraints: {constraints}"}
---

You are executing the REQUIREMENTS stage.

PESSIMISTIC-FIRST: Before defining what this feature should do, identify what it will BREAK.
1. Identify every file and integration point this change touches (use Glob/Grep)
2. For each, state the specific breakage scenario with affected file:line
3. List all questions the user must answer about failure modes
4. Generate risks with severity, affected files, and mitigation strategies

Then gather requirements:
1. Clear acceptance criteria (Given/When/Then format) with source field
2. Scope (in_scope / out_of_scope)
3. TDD test plan (unit, e2e, skill tests) mapped to ACs — tests come BEFORE planning
4. Risk registry with severity ratings

DO NOT add features not in the original request. Ask 2-3 clarifying questions max.

Write output to {TMPDIR}/.vcp/oneshot/req-{RAND}-{i}.json

Output JSON format — ALL fields required:
{
  "user_story": { "role": "...", "want": "...", "benefit": "..." },
  "acceptance_criteria": [
    { "id": "AC-1", "scenario": "...", "given": "...", "when": "...", "then": "...", "source": "original_request|user_answer" }
  ],
  "scope": { "in_scope": [...], "out_of_scope": [...], "assumptions": [...] },
  "impact_analysis": {
    "impacts": [
      { "id": "IMP-1", "affected_file": "file.ts", "affected_line": 42, "description": "...", "severity": "HIGH|MED|LOW", "evidence": "file:line — reason", "mitigation": "...", "decision_required": "..." }
    ],
    "questions": [
      { "id": "Q-1", "question": "...", "context": "IMP-1", "user_response": null }
    ]
  },
  "tdd_test_plan": {
    "unit_tests": [
      { "id": "UT-1", "description": "...", "ac_ids": ["AC-1"], "file": "tests/file.test.ts", "command": "npm test -- --grep '...'" }
    ],
    "e2e_tests": [...],
    "skill_tests": [...]
  },
  "risk_registry": [
    { "id": "R-1", "risk": "...", "severity": "HIGH|MED|LOW", "affected_files": ["..."], "mitigation": "...", "user_acknowledged": false }
  ],
  "approved_by": null,
  "approved_at": null,
  "needs_clarification": false,
  "clarification_questions": []
}

Multi-executor (analysts with synthesizer): If multiple executors configured:

  1. Non-synthesizer executors (all except last): each writes to {TMPDIR}/.vcp/oneshot/req-{RAND}-{i}.json
  2. Last executor (synthesizer) runs last with augmented prompt to read all prior outputs and write the canonical result

Step 5: Dispatch Executors

Resolve system prompt with stage/role composition:

bash
bun -e "
import { loadStageDefinition, getSystemPrompt, composePrompt } from '${CLAUDE_PLUGIN_ROOT}/scripts/system-prompts.ts';
const stage = loadStageDefinition('requirements', '${CLAUDE_PLUGIN_ROOT}/stages');
const role = getSystemPrompt('{executor.system_prompt}', '${CLAUDE_PLUGIN_ROOT}/system-prompts/built-in');
if (!stage) { console.error('FATAL: Stage definition not found'); process.exit(1); }
if (!role) { console.error('FATAL: Role prompt not found'); process.exit(1); }
console.log(composePrompt(stage, role));
"

Route by provider type:

  • subscription: Task(subagent_type: "general-purpose", model: "<model>", prompt: "<composed + task prompt>")
  • api: Bash(run_in_background: true)bun "${CLAUDE_PLUGIN_ROOT}/scripts/one-shot-runner.ts" --type api --output-id req-{RAND}-{i} --preset "{PRESET}" --model "{MODEL}" --cwd "${CLAUDE_PROJECT_DIR}" --task-stdin

Step 6: Collect Results and Handle Clarification

Read executor output from {TMPDIR}/.vcp/oneshot/req-{RAND}-*.json.

For API/CLI executors: The output file is wrapped in an envelope {"event":"complete","provider":"...","model":"...","result":"..."}. Parse the result field (which is a JSON string) to get the actual executor output. For subscription executors, the result is returned directly from the Task tool.

Check if executor needs clarification (two possible formats):

  • Field-level: executor output has "needs_clarification": true with "clarification_questions": [...]
  • Status-level: executor output is {"status": "needs_clarification", "clarification_questions": [...]} (API executors without AskUserQuestion)

If either form detected:

  1. Present questions to user via AskUserQuestion
  2. Re-dispatch synthesizer with answers appended (max 3 rounds)

Check impact analysis questions:

  1. Present each unresolved question to user via AskUserQuestion
  2. Record user responses in the impact analysis

Check risk registry:

  1. Present each unacknowledged risk to user via AskUserQuestion
  2. Record user acknowledgment

Step 7: Append to Plan File

Read the current plan file. Append three sections using the Edit tool.

If plan file doesn't have a header yet, create it first:

markdown
# Plan: {title from user story}
**Status:** requirements
**Pipeline:** {feature|bug-fix}
**Created:** {date}

---

Append ## Requirements section:

markdown
## Requirements

### User Story
**As a** {role}
**I want** {want}
**So that** {benefit}

### Acceptance Criteria
- [ ] **AC-1:** Given {given}, when {when}, then {then} [source: {source}]
- [ ] **AC-2:** Given {given}, when {when}, then {then} [source: {source}]

### Scope
**In scope:** {list}
**Out of scope:** {list}
**Assumptions:** {list}

### Impact Analysis (Pessimistic-First)

```json
{
  "impacts": [{impact objects from executor output}],
  "questions": [{question objects with user_response filled in}]
}

**Append `## TDD Test Plan` section:**
```markdown
## TDD Test Plan

### Unit Tests
| ID | Description | AC | File | Command |
|----|-------------|-----|------|---------|
| UT-1 | {description} | AC-1 | {file} | {command} |

### E2E Tests
| ID | Description | AC | Command |
|----|-------------|-----|---------|
| E2E-1 | {description} | AC-2 | {command} |

### Skill Tests
| ID | Description | AC | Skill Command |
|----|-------------|-----|---------------|
| SK-1 | {description} | AC-1 | {skill_command} |

Append ## Risk Registry section:

markdown
## Risk Registry

```json
{
  "risks": [{risk objects from executor output, with user_acknowledged updated}]
}

Unacknowledged risks block implementation.


---

## Step 8: Cleanup and Report

1. Remove temp files: `rm -f "{TMPDIR}/.vcp/oneshot/req-{RAND}-"*`
2. Present to the user:
   - Number of acceptance criteria
   - Key scope items
   - Impact analysis summary
   - TDD test plan summary
   - Risk registry status (how many acknowledged)
3. Suggest next step: `/dev-buddy-plan`

---

## Error Handling

| Scenario | Action |
|----------|--------|
| No executors configured | Report error, suggest `/dev-buddy-config` |
| All executors fail | Report error to user |
| Single executor fails | Continue with remaining |
| Clarification exceeded 3 rounds | Escalate to user |
| Plan file doesn't exist | Create with header |

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results