Skip to content

feat: optimize skill structure and improve content scores #339

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

Open
popey wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: optimize skill structure and improve content scores #339

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
55c6509
feat: optimize skill structure and improve content scores
popey Feb 25, 2026
7a1a328
Merge branch 'main' into improve/skill-optimization
subsy Feb 25, 2026
451aa31
Merge branch 'main' into improve/skill-optimization
subsy Mar 13, 2026
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
109 changes: 109 additions & 0 deletions skills/ralph-tui-create-beads-rust/EXAMPLES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Examples

## Full PRD-to-Beads Conversion Example

**Input PRD:**
```markdown
# PRD: Friends Outreach

Add ability to mark investors as "friends" for warm outreach.

## Quality Gates

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

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

## User Stories

### US-001: Add investorType field to investor table
**Description:** As a developer, I need 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.

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

### US-003: Filter investors by type
**Description:** As Ryan, I want to filter the list to see just friends or cold.

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

**Output beads:**
```bash
# Create epic (link back to source PRD)
br create --type=epic \
--title="Friends Outreach Track" \
--description="$(cat <<'EOF'
Warm outreach for deck feedback
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"

# US-001: No deps (first - creates schema)
br create --parent=ralph-tui-abc \
--title="US-001: Add investorType field to investor table" \
--description="$(cat <<'EOF'
As a developer, I need 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
EOF
)" \
--priority=1

# US-002: UI story (gets browser verification too)
br create --parent=ralph-tui-abc \
--title="US-002: Add type toggle to investor list rows" \
--description="$(cat <<'EOF'
As Ryan, I want to toggle investor type directly from the list.

## Acceptance Criteria
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
--priority=2

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

# US-003: UI story
br create --parent=ralph-tui-abc \
--title="US-003: Filter investors by type" \
--description="$(cat <<'EOF'
As Ryan, I want to filter the list to see just friends or cold.

## Acceptance Criteria
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
--priority=3

# Add dependency: US-003 depends on US-002
br dep add ralph-tui-003 ralph-tui-002
```
11 changes: 11 additions & 0 deletions skills/ralph-tui-create-beads-rust/REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Reference

## Differences from beads (Go version)

| Command | beads (`bd`) | beads-rust (`br`) |
|---------|--------------|-------------------|
| Create | `bd create` | `br create` |
| Dependencies | `bd dep add` | `br dep add` |
| Sync | `bd sync` | `br sync --flush-only` |
| Close | `bd close` | `br close` |
| Storage | `.beads/beads.jsonl` | `.beads/*.db` + JSONL export |
207 changes: 15 additions & 192 deletions skills/ralph-tui-create-beads-rust/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,44 +76,13 @@ EOF

## Story Size: The #1 Rule

**Each story 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 a story is too big, the agent runs out of context before finishing.

### Right-sized stories:
- Add a database column + migration
- Add a UI component to an existing page
- Update a server action with new logic
- Add a filter dropdown to a list

### Too big (split these):
- "Build the entire dashboard" → Split into: schema, queries, UI components, filters
- "Add authentication" → Split into: schema, middleware, login UI, session handling
- "Refactor the API" → Split into one story per endpoint or pattern

**Rule of thumb:** If you can't describe the change in 2-3 sentences, it's too big.

---

## Story Ordering: Dependencies First

Stories execute in dependency 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 doesn't exist yet)
2. ❌ Schema change
Each story must be completable in ONE ralph-tui iteration. Right-sized: single column/component/endpoint. Too big: entire dashboard/auth system (split these).

---

## Dependencies with `br dep add`

Use the `br dep add` command to specify which beads must complete first:
Stories execute in dependency order (schema → backend → UI). Use `br dep add` to specify which beads must complete first:

```bash
# Create the beads first
Expand All @@ -128,48 +97,25 @@ br dep add ralph-tui-003 ralph-tui-002 # US-003 depends on US-002

**Syntax:** `br dep add <issue> <depends-on>` — the issue depends on (is blocked by) depends-on.

ralph-tui will:
- Show blocked beads as "blocked" until dependencies complete
- Never select a bead for execution while its dependencies are open
- Include dependency context in the prompt when working on a bead

**Correct dependency order:**
1. Schema/database changes (no dependencies)
2. Backend logic (depends on schema)
3. UI components (depends on backend)
4. Integration/polish (depends on UI)
ralph-tui will show blocked beads as "blocked" until dependencies complete and include dependency context in the prompt when working on a bead.

---

## Acceptance Criteria: Quality Gates + Story-Specific

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

### Good criteria (verifiable):
- "Add `investorType` column to investor table with default 'cold'"
- "Filter dropdown has options: All, Cold, Friend"
- "Clicking toggle shows confirmation dialog"

### Bad criteria (vague):
- ❌ "Works correctly"
- ❌ "User can do X easily"
- ❌ "Good UX"
- ❌ "Handles edge cases"
Each bead's description should include story-specific acceptance criteria from the PRD, plus quality gates appended from the Quality Gates section.

---

## 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. **All stories**: `status: "open"`
7. **Acceptance criteria**: Story criteria + quality gates appended
8. **UI stories**: Also append UI-specific gates (browser verification)
3. **Dependencies**: Schema/database → backend → UI → integration (use `br dep add` after creating beads)
4. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Search for beads-rust priority references in the codebase
rg -i "priority|beads-rust|br create" --type md --type txt -A 3 -B 3

Repository: subsy/ralph-tui

Length of output: 34176

🏁 Script executed:

# Check the specific file mentioned in the review
cat -n skills/ralph-tui-create-beads-rust/SKILL.md | sed -n '60,125p'

Repository: subsy/ralph-tui

Length of output: 2772

🏁 Script executed:

# Look for any configuration or reference files related to beads-rust
fd -e toml -e yaml -e json -e md | xargs rg -l "beads-rust\|priority" 2>/dev/null | head -20

Repository: subsy/ralph-tui

Length of output: 41

🌐 Web query:

beads-rust "br create" priority values documentation

💡 Result:

For beads-rust (br) the br create priority is an integer on a 0–4 scale (lower number = higher priority):

  • 0 = Critical
  • 1 = High
  • 2 = Medium (default)
  • 3 = Low
  • 4 = Backlog [1][2]

Example usage:

  • br create --title "Fix prod crash" --type bug --priority 0 [1][2]

Sources: [1] [2]

🌐 Web query:

beads-rust priority 0-4 critical medium backlog meaning

💡 Result:

In beads-rust (the Beads tracker implementation in Rust), priority is a 0–4 scale where lower numbers mean “do sooner”:

  • 0 = Critical
  • 1 = High
  • 2 = Medium (default)
  • 3 = Low
  • 4 = Backlog (defer/maybe never) [1], [2], [3]

So “critical / medium / backlog” correspond to P0 / P2 / P4, respectively. [1], [2], [3]

How it’s used for picking work: tasks are typically sorted by priority ascending (0 first). [1]

Sources: [1] [2] [3]

Command example at line 70 omits critical priority value.

Line 70 shows --priority=[1-4] but beads-rust accepts 0–4 (where 0 = critical). This means users cannot set tasks as critical when creating beads. Update to --priority=[0-4] to match the complete priority mapping shown at line 115 and align with beads-rust semantics.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/ralph-tui-create-beads-rust/SKILL.md` at line 115, The command example
currently documents an incorrect priority range --priority=[1-4]; update the
example to --priority=[0-4] so it matches beads-rust's accepted values (0–4,
with 0 = critical) and the priority mapping described elsewhere in SKILL.md;
ensure any mention of the flag in examples or usage text uses the full range
(--priority=[0-4]) to avoid disallowing critical tasks.

5. **All stories**: `status: "open"`
6. **Acceptance criteria**: Story criteria + quality gates appended
7. **UI stories**: Also append UI-specific gates (browser verification)

---

Expand All @@ -196,111 +142,7 @@ Each is one focused change that can be completed and verified independently.

## Example

**Input PRD:**
```markdown
# PRD: Friends Outreach

Add ability to mark investors as "friends" for warm outreach.

## Quality Gates

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

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

## User Stories

### US-001: Add investorType field to investor table
**Description:** As a developer, I need 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.

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

### US-003: Filter investors by type
**Description:** As Ryan, I want to filter the list to see just friends or cold.

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

**Output beads:**
```bash
# Create epic (link back to source PRD)
br create --type=epic \
--title="Friends Outreach Track" \
--description="$(cat <<'EOF'
Warm outreach for deck feedback
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"

# US-001: No deps (first - creates schema)
br create --parent=ralph-tui-abc \
--title="US-001: Add investorType field to investor table" \
--description="$(cat <<'EOF'
As a developer, I need 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
EOF
)" \
--priority=1

# US-002: UI story (gets browser verification too)
br create --parent=ralph-tui-abc \
--title="US-002: Add type toggle to investor list rows" \
--description="$(cat <<'EOF'
As Ryan, I want to toggle investor type directly from the list.

## Acceptance Criteria
- [ ] Each row has Cold | Friend toggle
- [ ] Switching shows confirmation dialog
- [ ] On confirm: updates type in database
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
--priority=2

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

# US-003: UI story
br create --parent=ralph-tui-abc \
--title="US-003: Filter investors by type" \
--description="$(cat <<'EOF'
As Ryan, I want to filter the list to see just friends or cold.

## Acceptance Criteria
- [ ] Filter dropdown: All | Cold | Friend
- [ ] Filter persists in URL params
- [ ] pnpm typecheck passes
- [ ] pnpm lint passes
- [ ] Verify in browser using dev-browser skill
EOF
)" \
--priority=3

# Add dependency: US-003 depends on US-002
br dep add ralph-tui-003 ralph-tui-002
```
See [EXAMPLES.md](EXAMPLES.md) for a complete PRD-to-beads conversion.

---

Expand Down Expand Up @@ -329,34 +171,15 @@ ralph-tui run --tracker beads-rust --epic ralph-tui-abc
ralph-tui run --tracker beads-rust
```

ralph-tui will:
1. Work on beads within the specified epic (or select the best available task)
2. Close each bead when complete
3. Close the epic when all children are done
4. Output `<promise>COMPLETE</promise>` when epic is done
ralph-tui will work on beads, close each when complete, and output `<promise>COMPLETE</promise>` when the epic is done.

See [REFERENCE.md](REFERENCE.md) for differences from the Go version of beads.

---

## 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)
- [ ] Quality gates appended to every bead's acceptance criteria
- [ ] UI stories have browser verification (if specified in Quality Gates)
- [ ] Acceptance criteria are verifiable (not vague)
- [ ] No story depends on a later story (only earlier stories)
- [ ] Extracted Quality Gates from PRD
- [ ] Stories ordered by dependency (schema → backend → UI)
- [ ] Dependencies added with `br dep add` after creating beads
- [ ] Ran `br sync --flush-only` to export for git tracking

---

## Differences from beads (Go version)

| Command | beads (`bd`) | beads-rust (`br`) |
|---------|--------------|-------------------|
| Create | `bd create` | `br create` |
| Dependencies | `bd dep add` | `br dep add` |
| Sync | `bd sync` | `br sync --flush-only` |
| Close | `bd close` | `br close` |
| Storage | `.beads/beads.jsonl` | `.beads/*.db` + JSONL export |
Loading