docs(skills): condense skill docs for better agent context efficiency#358
docs(skills): condense skill docs for better agent context efficiency#358
Conversation
Reduce redundancy across all four SKILL.md files while keeping all critical content inline (worked examples, anti-patterns, reference tables). Agents only read SKILL.md at runtime, so splitting content into companion files would make it invisible during execution. Changes: - Merge "Story Ordering" into "Dependencies" section (was redundant) - Condense verbose ralph-tui behavior lists to single sentences - Tighten acceptance criteria guidance (keep good/bad, drop repetition) - Trim checklists to essentials (remove items that repeat body content) - Keep all worked examples, anti-patterns, and br/bd comparison inline Inspired by PR #339 (popey) which identified the redundancy issues.
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
WalkthroughDocumentation files for Ralph-TUI skills were updated to reduce verbosity and consolidate guidance. Changes include merging bullet lists into concise statements, restructuring sections for clarity, adding clarification that Ralph-TUI spawns a fresh agent per iteration with no memory of prior work, and simplifying narrative flow without altering the underlying workflow structure. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
skills/ralph-tui-create-beads/SKILL.md (1)
280-282: Consider matching checklist dependency wording to the full progression.Earlier sections use
schema → backend → UI → integration; checklist Line 282 stops at UI. For consistency, you may want to include integration here too.🤖 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 280 - 282, Update the checklist item "Stories ordered by dependency (schema → backend → UI)" to match the full progression used elsewhere by appending "→ integration" so it reads "Stories ordered by dependency (schema → backend → UI → integration) to maintain consistency with earlier sections.skills/ralph-tui-create-beads-rust/SKILL.md (1)
79-79: Consider adding a comma for improved readability.The new context about ralph-tui's memory model is valuable. For better readability, consider adding a comma after "iteration":
"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."
However, this could also be two separate sentences for even greater clarity:
"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."
🤖 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 79, Edit the sentence "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." to improve readability by either adding a comma after "iteration" (making it a single sentence) or by capitalizing and separating into two sentences as suggested; ensure "ralph-tui" is capitalized consistently if you split into two sentences ("Ralph-tui") to match surrounding style.skills/ralph-tui-create-json/SKILL.md (1)
168-168: Consider adding a comma for improved readability.Similar to the beads-rust skill, this important context about ralph-tui's memory model would benefit from a comma after "iteration" or splitting into two sentences:
"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."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/ralph-tui-create-json/SKILL.md` at line 168, The sentence "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." needs improved readability by adding a comma or splitting into two sentences; update the line containing "Each story must be completable in ONE ralph-tui iteration (~one agent context window)" to add a comma after "iteration" (or rewrite as two sentences as suggested) so it reads clearly and matches the style used in similar skills like the beads-rust example.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/ralph-tui-create-beads/SKILL.md`:
- Around line 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.
---
Nitpick comments:
In `@skills/ralph-tui-create-beads-rust/SKILL.md`:
- Line 79: Edit the sentence "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." to improve readability by either
adding a comma after "iteration" (making it a single sentence) or by
capitalizing and separating into two sentences as suggested; ensure "ralph-tui"
is capitalized consistently if you split into two sentences ("Ralph-tui") to
match surrounding style.
In `@skills/ralph-tui-create-beads/SKILL.md`:
- Around line 280-282: Update the checklist item "Stories ordered by dependency
(schema → backend → UI)" to match the full progression used elsewhere by
appending "→ integration" so it reads "Stories ordered by dependency (schema →
backend → UI → integration) to maintain consistency with earlier sections.
In `@skills/ralph-tui-create-json/SKILL.md`:
- Line 168: The sentence "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." needs improved readability by adding
a comma or splitting into two sentences; update the line containing "Each story
must be completable in ONE ralph-tui iteration (~one agent context window)" to
add a comma after "iteration" (or rewrite as two sentences as suggested) so it
reads clearly and matches the style used in similar skills like the beads-rust
example.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a088aa80-d618-40a5-88a3-aabc948971fa
📒 Files selected for processing (4)
skills/ralph-tui-create-beads-rust/SKILL.mdskills/ralph-tui-create-beads/SKILL.mdskills/ralph-tui-create-json/SKILL.mdskills/ralph-tui-prd/SKILL.md
| 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"` |
There was a problem hiding this comment.
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.
| 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.
1 participant
Summary
Motivation
Inspired by PR #339 (thanks @popey!) which correctly identified redundancy across skill files. That PR split content into companion files (EXAMPLES.md, REFERENCE.md, ANTI_PATTERNS.md), but since agents only read SKILL.md at runtime (
src/commands/create-prd.tsx:79-91,src/setup/skill-installer.ts:142-146), moved content would become invisible during skill execution.This PR takes the consolidation wins from #339 while keeping all high-signal content inline:
Results
What was removed
What was kept
Test plan
bun run typecheckpassesbun run buildpassesSummary by CodeRabbit