prd-converter

What this skill does

# SDK Bridge PRD Converter

Converts existing PRDs to the prd.json format that SDK Bridge uses for Agent Teams execution.

---

## The Job

Take a PRD (markdown file or text) and convert it to `prd.json` in your project directory.

---

## Output Format (Enhanced Schema)

```json
{
  "project": "[Project Name]",
  "branchName": "sdk-bridge/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2 with verification",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "depends_on": [],
      "related_to": [],
      "implementation_hint": "",
      "check_before_implementing": []
    }
  ]
}
```

### New Schema Fields (Phase 3 Enhancements)

- **depends_on** (array): IDs of stories that MUST complete before this one (e.g., `["US-001", "US-005"]`)
- **related_to** (array): IDs of stories that may contain related work to check (e.g., `["US-002"]`)
- **implementation_hint** (string): Guidance like "Check if US-005 already implemented this" or "Reuse existing badge component"
- **check_before_implementing** (array): Commands to run to verify existing implementation (e.g., `["grep cabin_class api.py"]`)

**When to use each:**
- `depends_on`: Hard dependency - this story CANNOT be done until dependency completes
- `related_to`: Soft dependency - check this story for similar code or patterns
- `implementation_hint`: Free-form text guidance for the agent
- `check_before_implementing`: Specific search commands to detect existing implementation

---

## Story Size: The Number One Rule

**Each story should be independently implementable by one teammate in a single session.**

SDK Bridge uses Agent Teams — multiple teammates run in parallel, each claiming and implementing one story at a time. Stories must be self-contained: a teammate implementing US-003 cannot rely on in-progress work from another teammate implementing US-002.

### Right-sized stories (3-5 criteria):
**Data Layer:**
- Add new field to data model with validation
- Create migration for schema change
- Implement data access method for new query

**Logic Layer:**
- Add business rule validation
- Implement calculation or transformation logic
- Add error handling for specific failure case

**Presentation Layer:**
- Create reusable component with basic functionality
- Add interaction handler (click, submit, etc.)
- Implement visual state (loading, error, success)

### Too big (8+ criteria - must split):
**Pattern:** "Build entire [subsystem]"
- ❌ Single story: All layers combined
- ✅ Split into: Data → Logic → Presentation → Integration

**Pattern:** "Add complex [feature]"
- ❌ Single story: All configuration + functionality + edge cases
- ✅ Split into: Core behavior → Options → Error handling

**Pattern:** "Refactor [large module]"
- ❌ Single story: Entire module at once
- ✅ Split into: One story per file/function/component

**Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big.

**Validation Rules:**
- ✅ **Ideal:** 3-5 acceptance criteria (including typecheck/browser verification)
- ⚠️ **Warning:** 6-7 criteria - consider splitting if possible
- ❌ **Too large:** 8+ criteria - MUST split into multiple stories
- **Time target:** Each story should complete in 10-20 minutes

**After converting, check for oversized stories:**
```bash
jq '.userStories[] | select((.acceptanceCriteria | length) > 7) | "\(.id): \(.title) - \(.acceptanceCriteria | length) criteria (TOO LARGE)"'
```

If you find stories with 8+ criteria, recommend splitting them in your output.

---

## Story Ordering: Dependencies First

Stories execute in priority order. Earlier stories must not depend on later ones.

**Correct order:**
1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

**Wrong order:**
1. UI component (depends on schema that does not exist yet)
2. Schema change

---

## Acceptance Criteria: Must Be Verifiable

Each criterion must be something SDK Bridge can CHECK, not something vague.

### Good criteria (verifiable):
- "Add `status` column to tasks table with default 'pending'"
- "Filter dropdown has options: All, Active, Completed"
- "Clicking delete shows confirmation dialog"
- "Typecheck passes"
- "Tests pass"

### Bad criteria (vague):
- "Works correctly"
- "User can do X easily"
- "Good UX"
- "Handles edge cases"

### Always include as final criterion:
```
"Typecheck passes"
```

For stories with testable logic, also include:
```
"Tests pass"
```

### For stories that change UI, also include:
```
"Verify in browser using dev-browser skill"
```

Frontend stories are NOT complete until visually verified. SDK Bridge will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

---

## Conversion Rules

1. **Each user story becomes one JSON entry**
2. **IDs**: Sequential (US-001, US-002, etc.)
3. **Priority**: Based on dependency order, then document order
4. **All stories**: `passes: false` and empty `notes`
5. **branchName**: Derive from feature name, kebab-case, prefixed with `sdk-bridge/`
6. **Always add**: "Typecheck passes" to every story's acceptance criteria
7. **Infer dependencies**: Detect `depends_on`, `related_to`, and add hints (see below)

### Dependency Inference Rules

**Auto-detect `depends_on`:**
- Backend stories depend on schema/database stories
- UI stories depend on backend API/service stories
- Integration stories depend on component stories
- Look for explicit "Depends on: US-XXX" in PRD

**⚠️ Avoid False Dependencies:**
- NOT all stories need to depend on the previous story
- Stories can run in parallel if they work on different files/modules
- Only add `depends_on` for TRUE blocking dependencies
- **Test:** Can this story be implemented without the previous story being complete? If yes, don't add dependency

**True Dependencies (add `depends_on`):**
- Data model required before business logic using it
- API endpoint required before UI consuming it
- Authentication required before protected features
- Base component required before extensions/variants
- Configuration required before features using it

**False Dependencies (NO `depends_on`, use `related_to`):**
- Two UI components in different parts of the app
- Two API endpoints serving different purposes
- Two database tables with no foreign key relationship
- Parallel implementation tracks (e.g., UI theme + API layer)
- Sequential numbering doesn't imply dependency

**Auto-detect `related_to`:**
- Stories working on the same file/module
- Stories in the same feature area (e.g., all "priority" stories)
- Frontend and backend halves of the same feature
- Later stories in a sequence (US-007 related to US-005, US-006)

**Generate `implementation_hint`:**
- If `related_to` is not empty: "Check US-XXX for similar implementation patterns"
- If UI story follows data/API story: "US-XXX may have already implemented the data layer for this"
- If splitting a feature: "This is part of [feature area], coordinate with US-XXX for consistency"
- If extending existing work: "Builds on US-XXX, review that implementation before starting"

**Generate `check_before_implementing`:**
Extract key identifiers from acceptance criteria and create search commands:

**For data models:** `grep -rn "[ModelName]\|[field_name]" src/models/`
**For API/services:** `grep -rn "[endpoint_name]\|[function_name]" src/api/ src/services/`
**For UI components:** `grep -rn "[ComponentName]" src/components/ src/pages/`
**For configuration:** `grep -rn "[config_key]" config/ .env`

Use actual identifiers from the story (class names, function names, field names), not generic terms.

### Example: Dependency D