Skip to content

docs(skills): condense skill docs for better agent context efficiency #358

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
subsy wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(skills): condense skill docs for better agent context efficiency #358

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
85 changes: 16 additions & 69 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,19 @@ EOF

## Story Size: The #1 Rule

**Each story must be completable in ONE ralph-tui iteration (~one agent context window).**
Each story must be completable in ONE ralph-tui iteration (~one agent context window). ralph-tui spawns a fresh agent per iteration with no memory of previous work.

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:** Add a database column + migration. Add a UI component. Update a server action. Add a filter dropdown.

### 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
**Too big (split these):** "Build the entire dashboard" → schema, queries, UI, filters. "Add authentication" → schema, middleware, login UI, sessions.

**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

---

## 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 → integration). Use `br dep add` to specify which beads must complete first:

```bash
# Create the beads first
Expand All @@ -128,48 +103,27 @@ 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"
Each bead's description should include story-specific acceptance criteria from the PRD, plus quality gates appended from the Quality Gates section.

### Bad criteria (vague):
- ❌ "Works correctly"
- ❌ "User can do X easily"
- ❌ "Good UX"
- ❌ "Handles edge cases"
Criteria must be verifiable: "Add `investorType` column with default 'cold'" is good. "Works correctly" or "Good UX" is bad.

---

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

---

Expand Down Expand Up @@ -329,23 +283,16 @@ 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.

---

## 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)
- [ ] Extracted Quality Gates from PRD
- [ ] Each story is completable in one iteration
- [ ] Stories 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)
- [ ] Dependencies added with `br dep add` after creating beads
- [ ] Ran `br sync --flush-only` to export for git tracking

Expand Down
85 changes: 16 additions & 69 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 @@ -76,44 +76,19 @@ EOF

## Story Size: The #1 Rule

**Each story must be completable in ONE ralph-tui iteration (~one agent context window).**
Each story must be completable in ONE ralph-tui iteration (~one agent context window). ralph-tui spawns a fresh agent per iteration with no memory of previous work.

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:** Add a database column + migration. Add a UI component. Update a server action. Add a filter dropdown.

### 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
**Too big (split these):** "Build the entire dashboard" → schema, queries, UI, filters. "Add authentication" → schema, middleware, login UI, sessions.

**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

---

## Dependencies with `bd dep add`

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

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

**Syntax:** `bd 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"
Each bead's description should include story-specific acceptance criteria from the PRD, plus quality gates appended from the Quality Gates section.

### Bad criteria (vague):
- ❌ "Works correctly"
- ❌ "User can do X easily"
- ❌ "Good UX"
- ❌ "Handles edge cases"
Criteria must be verifiable: "Add `investorType` column with default 'cold'" is good. "Works correctly" or "Good UX" is bad.

---

## 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 `bd dep add` after creating beads)
4. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
5. **All stories**: `status: "open"`
Comment on lines +122 to +124
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 13, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Priority scale is internally inconsistent in this document.

Line 123 says 0=critical, but earlier output format uses --priority=[1-4] (Line 70) and examples use 1/2/3. Please align one scale across all sections to avoid incorrect bead creation.

Suggested doc fix 
-4. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
+4. **Priority**: Based on dependency order, then document order (1=high, 2=medium, 3=low, 4=backlog)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
3. **Dependencies**: Schema/database → backend → UI → integration (use `bd dep add` after creating beads)
4. **Priority**: Based on dependency order, then document order (0=critical, 2=medium, 4=backlog)
5. **All stories**: `status: "open"`
3. **Dependencies**: Schema/database → backend → UI → integration (use `bd dep add` after creating beads)
4. **Priority**: Based on dependency order, then document order (1=high, 2=medium, 3=low, 4=backlog)
5. **All stories**: `status: "open"`
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/ralph-tui-create-beads/SKILL.md` around lines 122 - 124, The priority
scale is inconsistent: the CLI flag string "--priority=[1-4]" and examples use
1/2/3 but the "Priority:" line uses "0=critical" and "4=backlog"; update the
document to use a single scale (recommend changing "0=critical" to "1=critical"
and clarify "1=critical, 2=high, 3=medium, 4=backlog") and then adjust the
"Priority:" line and any examples or descriptions that reference 0/1/2/3 to the
chosen 1-4 scale so they match the "--priority=[1-4]" flag and examples.

6. **Acceptance criteria**: Story criteria + quality gates appended
7. **UI stories**: Also append UI-specific gates (browser verification)

---

Expand Down Expand Up @@ -317,21 +271,14 @@ ralph-tui run --tracker beads --epic ralph-tui-abc
ralph-tui run --tracker beads
```

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.

---

## 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)
- [ ] Extracted Quality Gates from PRD
- [ ] Each story is completable in one iteration
- [ ] Stories 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)
- [ ] Dependencies added with `bd dep add` after creating beads
57 changes: 9 additions & 48 deletions skills/ralph-tui-create-json/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,67 +165,38 @@ Use `"passes": false` for incomplete stories, `"passes": true` for completed.

## Story Size: The #1 Rule

**Each story must be completable in ONE ralph-tui iteration (~one agent context window).**
Each story must be completable in ONE ralph-tui iteration (~one agent context window). Ralph-tui spawns a fresh agent per iteration with no memory of previous work.

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:** Add a database column + migration. Add a UI component. Update a server action. Add a filter dropdown.

### 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
**Too big (split these):** "Build the entire dashboard" → schema, queries, UI, filters. "Add authentication" → schema, middleware, login UI, sessions.

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

---

## Dependencies with `dependsOn`

Use the `dependsOn` array to specify which stories must complete first:
Use the `dependsOn` array to specify which stories must complete first. Ralph-tui will show stories as "blocked" until dependencies complete.

```json
{
"id": "US-002",
"title": "Create API endpoints",
"dependsOn": ["US-001"], // Won't be selected until US-001 passes
"dependsOn": ["US-001"],
...
}
```

Ralph-tui will:
- Show US-002 as "blocked" until US-001 completes
- Never select US-002 for execution while US-001 is open
- Include "Prerequisites: US-001" in the prompt when working on US-002

**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)
**Correct dependency order:** Schema/database → backend → UI → integration.

---

## Acceptance Criteria: Quality Gates + Story-Specific

Each story's acceptance criteria should include:
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)
Each story's acceptance criteria should include story-specific criteria from the PRD, plus quality gates appended from the Quality Gates section.

### Good criteria (verifiable):
- "Add `status` column to tasks table with default 'open'"
- "Filter dropdown has options: All, Open, Closed"
- "Clicking delete shows confirmation dialog"

### Bad criteria (vague):
- ❌ "Works correctly"
- ❌ "User can do X easily"
- ❌ "Good UX"
- ❌ "Handles edge cases"
Criteria must be verifiable: "Add `status` column with default 'open'" is good. "Works correctly" or "Good UX" is bad.

---

Expand Down Expand Up @@ -364,23 +335,13 @@ After creating prd.json:
ralph-tui run --prd ./tasks/prd.json
```

Ralph-tui will:
1. Load stories from prd.json
2. Select the highest-priority story with `passes: false` and no blocking dependencies
3. Generate a prompt with story details + acceptance criteria
4. Run the agent to implement the story
5. Mark `passes: true` on completion
6. Repeat until all stories pass

---

## Checklist Before Saving

- [ ] Extracted Quality Gates from PRD (or asked user if missing)
- [ ] Extracted Quality Gates from PRD
- [ ] Each story completable in one iteration
- [ ] Stories ordered by dependency (schema → backend → UI)
- [ ] `dependsOn` correctly set for each story
- [ ] Quality gates appended to every story's acceptance criteria
- [ ] UI stories have browser verification (if specified in Quality Gates)
- [ ] Acceptance criteria are verifiable (not vague)
- [ ] No circular dependencies
Loading
Loading