Skip to content

feat: Add work item type distinction #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
dvic wants to merge 1 commit into from
Closed

feat: Add work item type distinction #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 79 additions & 52 deletions skills/ralph-tui-create-beads/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ Converts PRDs to beads (epic + child tasks) for ralph-tui autonomous execution.
Take a PRD (markdown file or text) and create beads in `.beads/beads.jsonl`:
1. **Extract Quality Gates** from the PRD's "Quality Gates" section
2. Create an **epic** bead for the feature
3. Create **child beads** for each user story (with quality gates appended)
3. Create **child beads** for each work item (with quality gates appended)
4. Set up **dependencies** between beads (schema → backend → UI)
5. Output ready for `ralph-tui run --tracker beads`
5. Map **work item type** to beads `--type=` flag
6. Output ready for `ralph-tui run --tracker beads`

---

Expand Down Expand Up @@ -54,26 +55,41 @@ Beads use `bd create` command:
bd create --type=epic \
--title="[Feature Name]" \
--description="[Feature description from PRD]" \
--labels="ralph,feature"
--labels="ralph"

# Create child bead (with quality gates in acceptance criteria)
bd create \
--type=[story|task] \
--parent=EPIC_ID \
--title="[Story Title]" \
--description="[Story description with acceptance criteria INCLUDING quality gates]" \
--title="[Work Item Title]" \
--description="[Description with acceptance criteria INCLUDING quality gates]" \
--priority=[1-4] \
--labels="ralph,task"
--labels="ralph"
```

---

## Story Size: The #1 Rule
## Type Mapping

**Each story must be completable in ONE ralph-tui iteration (~one agent context window).**
Map work item prefixes to beads `--type=` flag (case-insensitive):

ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If a story is too big, the agent runs out of context before finishing.
| Prefix | `--type=` | Notes |
|--------|-----------|-------|
| US-xxx | story | User-facing features ("As a user, I want...") |
| TA-xxx | task | Technical work (schema, backend, refactoring, bugs, maintenance) |
| other | task | Default for unknown prefixes (including legacy FR-xxx) |

### Right-sized stories:
**Labels strategy:** Use `--labels="ralph"` for grouping only. Type classification uses `--type=` flag, not labels.

---

## Work Item Size: The #1 Rule

**Each work item must be completable in ONE ralph-tui iteration (~one agent context window).**

ralph-tui spawns a fresh agent instance per iteration with no memory of previous work. If an item is too big, the agent runs out of context before finishing.

### Right-sized items:
- Add a database column + migration
- Add a UI component to an existing page
- Update a server action with new logic
Expand All @@ -88,9 +104,9 @@ ralph-tui spawns a fresh agent instance per iteration with no memory of previous

---

## Story Ordering: Dependencies First
## Work Item Ordering: Dependencies First

Stories execute in dependency order. Earlier stories must not depend on later ones.
Items execute in dependency order. Earlier items must not depend on later ones.

**Correct order:**
1. Schema/database changes (migrations)
Expand Down Expand Up @@ -134,10 +150,10 @@ ralph-tui will:

---

## Acceptance Criteria: Quality Gates + Story-Specific
## Acceptance Criteria: Quality Gates + Item-Specific

Each bead's description should include acceptance criteria with:
1. **Story-specific criteria** from the PRD (what this story accomplishes)
1. **Item-specific criteria** from the PRD (what this work item accomplishes)
2. **Quality gates** from the PRD's Quality Gates section (appended at the end)

### Good criteria (verifiable):
Expand All @@ -156,14 +172,15 @@ Each bead's description should include acceptance criteria with:
## Conversion Rules

1. **Extract Quality Gates** from PRD first
2. **Each user story → one bead**
3. **First story**: No dependencies (creates foundation)
4. **Subsequent stories**: Depend on their predecessors (UI depends on backend, etc.)
5. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
6. **Labels**: Epic gets `ralph,feature`; Tasks get `ralph,task`
7. **All stories**: `status: "open"`
8. **Acceptance criteria**: Story criteria + quality gates appended
9. **UI stories**: Also append UI-specific gates (browser verification)
2. **Each work item → one bead**
3. **Map prefix to type**: US-xxx → story, TA-xxx (and others) → task
4. **First item**: No dependencies (creates foundation)
5. **Subsequent items**: Depend on their predecessors (UI depends on backend, etc.)
6. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
7. **Labels**: All beads get `ralph` label only (type is in `--type=` flag)
8. **All items**: `status: "open"`
9. **Acceptance criteria**: Item criteria + quality gates appended
10. **UI items**: Also append UI-specific gates (browser verification)

---

Expand All @@ -175,11 +192,11 @@ If a PRD has big features, split them:
> "Add friends outreach track with different messaging"

**Split into:**
1. US-001: Add investorType field to database
1. TA-001: Add investorType field to database
2. US-002: Add type toggle to investor list UI
3. US-003: Create friend-specific phase progression logic
4. US-004: Create friend message templates
5. US-005: Wire up task generation for friends
3. TA-003: Create friend-specific phase progression logic
4. TA-004: Create friend message templates
5. TA-005: Wire up task generation for friends
6. US-006: Add filter by type
7. US-007: Update new investor form
8. US-008: Update dashboard counts
Expand All @@ -198,36 +215,41 @@ Add ability to mark investors as "friends" for warm outreach.

## Quality Gates

These commands must pass for every user story:
These commands must pass for every work item:
- `pnpm typecheck` - Type checking
- `pnpm lint` - Linting

For UI stories, also include:
For UI items, also include:
- Verify in browser using dev-browser skill

## User Stories
## Work Items

### US-001: Add investorType field to investor table
**Description:** As a developer, I need to categorize investors as 'cold' or 'friend'.
### TA-001: Add investorType field to investor table
**Type:** task
**Description:** Add investorType column to categorize investors as 'cold' or 'friend'.

**Acceptance Criteria:**
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully

### US-002: Add type toggle to investor list rows
**Description:** As Ryan, I want to toggle investor type directly from the list.
**Type:** story
**Description:** As Ryan, I want to toggle investor type directly from the list so that I can quickly categorize investors.

**Acceptance Criteria:**
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
**Depends on:** TA-001

### US-003: Filter investors by type
**Description:** As Ryan, I want to filter the list to see just friends or cold.
**Type:** story
**Description:** As Ryan, I want to filter the list to see just friends or cold so that I can focus on specific investor groups.

**Acceptance Criteria:**
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params
**Depends on:** US-002
```

**Output beads:**
Expand All @@ -236,25 +258,27 @@ For UI stories, also include:
bd create --type=epic \
--title="Friends Outreach Track" \
--description="Warm outreach for deck feedback" \
--labels="ralph,feature"
--labels="ralph"

# US-001: No deps (first - creates schema)
bd create --parent=ralph-tui-abc \
--title="US-001: Add investorType field to investor table" \
--description="As a developer, I need to categorize investors as 'cold' or 'friend'.
# TA-001: Task, no deps (first - creates schema)
bd create --type=task \
--parent=ralph-tui-abc \
--title="TA-001: Add investorType field to investor table" \
--description="Add investorType column to categorize investors as 'cold' or 'friend'.

## Acceptance Criteria
- [ ] Add investorType column: 'cold' | 'friend' (default 'cold')
- [ ] Generate and run migration successfully
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes" \
--priority=1 \
--labels="ralph,task"
--labels="ralph"

# US-002: UI story (gets browser verification too)
bd create --parent=ralph-tui-abc \
# US-002: Story, UI (gets browser verification too)
bd create --type=story \
--parent=ralph-tui-abc \
--title="US-002: Add type toggle to investor list rows" \
--description="As Ryan, I want to toggle investor type directly from the list.
--description="As Ryan, I want to toggle investor type directly from the list so that I can quickly categorize investors.

## Acceptance Criteria
- [ ] Each row has Cold | Friend toggle
Expand All @@ -264,15 +288,16 @@ bd create --parent=ralph-tui-abc \
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill" \
--priority=2 \
--labels="ralph,task"
--labels="ralph"

# Add dependency: US-002 depends on US-001
# Add dependency: US-002 depends on TA-001
bd dep add ralph-tui-002 ralph-tui-001

# US-003: UI story
bd create --parent=ralph-tui-abc \
# US-003: Story, UI
bd create --type=story \
--parent=ralph-tui-abc \
--title="US-003: Filter investors by type" \
--description="As Ryan, I want to filter the list to see just friends or cold.
--description="As Ryan, I want to filter the list to see just friends or cold so that I can focus on specific investor groups.

## Acceptance Criteria
- [ ] Filter dropdown: All | Cold | Friend
Expand All @@ -281,7 +306,7 @@ bd create --parent=ralph-tui-abc \
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill" \
--priority=3 \
--labels="ralph,task"
--labels="ralph"

# Add dependency: US-003 depends on US-002
bd dep add ralph-tui-003 ralph-tui-002
Expand Down Expand Up @@ -313,10 +338,12 @@ ralph-tui will:
## Checklist Before Creating Beads

- [ ] Extracted Quality Gates from PRD (or asked user if missing)
- [ ] Each story is completable in one iteration (small enough)
- [ ] Stories are ordered by dependency (schema → backend → UI)
- [ ] Each work item is completable in one iteration (small enough)
- [ ] Work items are ordered by dependency (schema → backend → UI)
- [ ] Mapped item prefixes to `--type=` flag (US-xxx → story, TA-xxx → task)
- [ ] Using `--labels="ralph"` only (no type in labels)
- [ ] Quality gates appended to every bead's acceptance criteria
- [ ] UI stories have browser verification (if specified in Quality Gates)
- [ ] UI items have browser verification (if specified in Quality Gates)
- [ ] Acceptance criteria are verifiable (not vague)
- [ ] No story depends on a later story (only earlier stories)
- [ ] No item depends on a later item (only earlier items)
- [ ] Dependencies added with `bd dep add` after creating beads
Loading