feat: optimize skill structure and improve content scores#339
feat: optimize skill structure and improve content scores#339popey wants to merge 3 commits intosubsy:mainfrom
Conversation
Improved all 4 skills from 89% average (77% content) to 93% average (85% content) by restructuring content and reducing redundancy: Changes: - Moved detailed examples to separate EXAMPLES.md files - Extracted anti-patterns to ANTI_PATTERNS.md (ralph-tui-create-json) - Created REFERENCE.md for tool comparison (ralph-tui-create-beads-rust) - Consolidated repetitive dependency ordering explanations - Streamlined story sizing guidance - Reduced redundant acceptance criteria examples - Simplified quality gates explanations - Trimmed verbose checklist items All skills maintain 100% description scores while improving content clarity and reducing token usage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
@popey is attempting to deploy a commit to the plgeek Team on Vercel. A member of the Team first needs to authorize it. |
WalkthroughThis PR restructures documentation across multiple Ralph TUI skills by extracting embedded examples and anti-patterns into dedicated markdown files. It adds EXAMPLES.md to several skills, introduces ANTI_PATTERNS.md for JSON schema validation guidance, adds REFERENCE.md comparing beads and beads-rust command equivalents, and consolidates main SKILL.md files by removing verbose examples in favour of brief references. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 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)
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: 3
🤖 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-rust/SKILL.md`:
- 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.
In `@skills/ralph-tui-create-beads/SKILL.md`:
- Line 115: Update the priority mapping line that currently reads "Priority:
Based on dependency order, then document order (0=critical, 2=medium,
4=backlog)" so it aligns with the documented --priority=[1-4] range and
examples; replace the incorrect 0/2/4 mapping with a mapping such as
"1=critical, 2=medium, 3–4=backlog" in both SKILL.md and SKILL.md for the Rust
variant (look for the "Priority:" sentence in each file and adjust the numeric
mapping accordingly).
In `@skills/ralph-tui-create-json/SKILL.md`:
- Line 115: Update the dependency-order text so both places use the same
canonical sequence; change the "Correct dependency order:" line that currently
reads "Schema/database → backend → UI → integration" to match the checklist's
order "schema → backend → UI" (or vice versa if you prefer to include
integration everywhere), and ensure the checklist and the "Correct dependency
order:" header both use identical capitalization and arrow formatting; update
the symbol strings in SKILL.md (the "Correct dependency order:" line and the
checklist block) to be consistent.
ℹ️ Review info
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
skills/ralph-tui-create-beads-rust/EXAMPLES.mdskills/ralph-tui-create-beads-rust/REFERENCE.mdskills/ralph-tui-create-beads-rust/SKILL.mdskills/ralph-tui-create-beads/EXAMPLES.mdskills/ralph-tui-create-beads/SKILL.mdskills/ralph-tui-create-json/ANTI_PATTERNS.mdskills/ralph-tui-create-json/EXAMPLES.mdskills/ralph-tui-create-json/SKILL.mdskills/ralph-tui-prd/EXAMPLES.mdskills/ralph-tui-prd/SKILL.md
| 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) |
There was a problem hiding this comment.
🧩 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 3Repository: 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 -20Repository: 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.
| 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) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n skills/ralph-tui-create-beads/SKILL.md | sed -n '65,120p'Repository: subsy/ralph-tui
Length of output: 2487
🏁 Script executed:
find skills -type f \( -name "SKILL.md" -o -name "EXAMPLES.md" -o -name "REFERENCE.md" -o -name "ANTI_PATTERNS.md" \) -exec grep -l "priority" {} \;Repository: subsy/ralph-tui
Length of output: 309
🏁 Script executed:
rg -n "priority|--priority" skills/ -t md --max-count 20Repository: subsy/ralph-tui
Length of output: 2536
🏁 Script executed:
grep -n "priority" skills/ralph-tui-create-beads/EXAMPLES.mdRepository: subsy/ralph-tui
Length of output: 113
🏁 Script executed:
cat -n skills/ralph-tui-create-beads/SKILL.md | sed -n '110,130p'Repository: subsy/ralph-tui
Length of output: 889
🏁 Script executed:
cat -n skills/ralph-tui-create-beads-rust/SKILL.md | sed -n '110,130p'Repository: subsy/ralph-tui
Length of output: 889
Priority scale in conversion rules contradicts the command specification and usage examples.
Line 70 documents --priority=[1-4] as the valid range, but line 115 maps priority to 0=critical, 2=medium, 4=backlog—values 0 and inconsistent numbering that falls outside [1-4]. The EXAMPLES.md file demonstrates actual usage with --priority=1, --priority=2, and --priority=3. Correct line 115 to align with the [1-4] range; suggest 1=critical, 2=medium, 3–4=backlog based on documented examples. This issue exists identically in both skills/ralph-tui-create-beads/SKILL.md and skills/ralph-tui-create-beads-rust/SKILL.md.
🤖 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` at line 115, Update the priority
mapping line that currently reads "Priority: Based on dependency order, then
document order (0=critical, 2=medium, 4=backlog)" so it aligns with the
documented --priority=[1-4] range and examples; replace the incorrect 0/2/4
mapping with a mapping such as "1=critical, 2=medium, 3–4=backlog" in both
SKILL.md and SKILL.md for the Rust variant (look for the "Priority:" sentence in
each file and adjust the numeric mapping accordingly).
| 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. |
There was a problem hiding this comment.
Dependency order wording is now inconsistent with the checklist.
Line 115 includes integration, but the checklist later still reflects schema → backend → UI only. Please align both to one canonical order to avoid mixed guidance.
🤖 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 115, Update the
dependency-order text so both places use the same canonical sequence; change the
"Correct dependency order:" line that currently reads "Schema/database → backend
→ UI → integration" to match the checklist's order "schema → backend → UI" (or
vice versa if you prefer to include integration everywhere), and ensure the
checklist and the "Correct dependency order:" header both use identical
capitalization and arrow formatting; update the symbol strings in SKILL.md (the
"Correct dependency order:" line and the checklist block) to be consistent.
|
Hey @popey thanks - will take a look at this! I know a lot of the folks from Tessl as I used to work with them at Snyk :) |
|
Hahah! I can't get away from the Snykers! :D |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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.
2 participants
Hullo 👋 @subsy (from just up the road in Farnborough)
Nice work on ralph-tui - I do love a nice terminal app <3.
I noticed you had 4 skills bundled with the project and thought I'd take a look at their structure.
I ran them some evaluation tooling we use at work. All 4 skills were already in great shape with strong descriptions, but I spotted some opportunities to tighten up the content structure. Here are the improvements:
Changes Summary
Click to expand detailed changes
Structure improvements:
EXAMPLES.mdfor each skill to keep the main SKILL.md focused on essentials while preserving full working examplesREFERENCE.mdfor tool comparison table (beads-rust) andANTI_PATTERNS.mdfor schema validation examples (create-json)Content refinements:
Results:
Disclosure
Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute.
If you want to run evals yourself, click here.
Thanks in advance 🙏
Summary by CodeRabbit
Release Notes