@seanyao/roll 3.624.1 → 3.624.2

package/skills/roll-doctor/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: roll-doctor
+license: MIT
+allowed-tools: "Read, Bash, Edit"
+description: "Load when diagnosing Roll toolchain health, conventions sync, skill file health, templates, symlinks, config validity, or installation integrity."
+---
+# Roll Doctor
+
+## Gotchas
+
+- Doctor diagnoses toolchain and convention health; it should fail loud on broken contracts rather than hiding drift.
+- Skill health checks belong here only as diagnostics; changing skill content still happens in roll-skills.
+
+诊断 Roll 工具链健康状态。快速定位 skill 不工作、convention 不同步、symlink 断裂等问题。
+
+## When to Use
+
+- "roll 怎么不工作了"
+- "skill 找不到了"
+- "convention 没有同步"
+- "$roll-debug 不响应"
+- 任何 Roll 相关功能异常
+
+## Checks
+
+### 1. Roll Installation
+
+```bash
+# Verify ROLL_HOME structure
+ls -la ~/.roll/
+ls -la ~/.roll/skills/
+ls -la ~/.roll/conventions/
+```
+
+Expected:
+- `~/.roll/` exists
+- `~/.roll/skills/` has roll-* directories
+- `~/.roll/conventions/global/` has AGENTS.md, CLAUDE.md, etc.
+- `~/.roll/conventions/templates/` has backend-service, cli, frontend-only, fullstack
+
+### 2. Skill Health
+
+```bash
+# List all skills and check YAML frontmatter
+for f in ~/.roll/skills/*/SKILL.md; do
+  echo "=== $(basename $(dirname $f)) ==="
+  head -5 "$f"
+done
+```
+
+Check:
+- Each skill directory has `SKILL.md`
+- YAML frontmatter has `name:` and `description:`
+- No duplicate `name` values across skills
+- File is readable markdown
+
+When diagnosing a roll-skills checkout, run the first-class skill audit:
+
+```bash
+node scripts/audit-skills.mjs
+node scripts/audit-skills.mjs --json
+node scripts/audit-skills.mjs --strict
+```
+
+Check:
+- Every description starts with `Load when...` and stays at 50 words or fewer
+- Every skill has positive and negative route cases in `route-cases/skills.json`
+- Every skill has Gotchas / Known Failure Modes coverage
+- Hub/spoke integrity has no missing or unreferenced `references/`, `assets/`, or `scripts/` files
+- Oversized hubs either split below 250 lines or carry an explicit reviewed waiver
+
+### 3. Symlinks
+
+```bash
+# Claude Code
+ls -la ~/.claude/skills/roll-*
+
+# Antigravity (agy — reuses ~/.gemini/, if exists)
+ls -la ~/.gemini/skills/roll-* 2>/dev/null
+
+```
+
+Check:
+- Each symlink exists
+- Each symlink points to valid target in `~/.roll/skills/`
+- No broken symlinks (red in ls output)
+
+### 4. Conventions Sync
+
+```bash
+# Check roll.md sync
+diff ~/.roll/conventions/global/CLAUDE.md ~/.claude/roll.md
+
+# Check CLAUDE.md includes @roll.md
+grep "@roll.md" ~/.claude/CLAUDE.md
+```
+
+Check:
+- `~/.claude/roll.md` exists and matches `~/.roll/conventions/global/CLAUDE.md`
+- `~/.claude/CLAUDE.md` contains `@roll.md` reference
+- `~/.claude/CLAUDE.md` is not missing or stale
+
+### 5. Template Integrity
+
+```bash
+# Global conventions
+ls ~/.roll/conventions/global/
+
+# Project type templates
+for t in backend-service cli frontend-only fullstack; do
+  ls ~/.roll/conventions/templates/$t/
+done
+
+# New project template
+ls ~/.roll/template/
+```
+
+Check:
+- All expected files present in each directory
+- No missing AGENTS.md, CLAUDE.md, or GEMINI.md
+
+### 6. Config
+
+```bash
+cat ~/.roll/config.yaml
+```
+
+Check:
+- File exists and is valid YAML
+- Has required `ai_tool_name` or `ai_claude` entries
+
+### 7. Peer Review
+
+```bash
+# Peer state directory
+ls -la ~/.roll/.peer-state/ 2>/dev/null || echo "missing"
+
+# Peer config in config.yaml
+grep "peer_" ~/.roll/config.yaml 2>/dev/null || echo "no peer config"
+
+# Available peer CLIs
+for tool in claude kimi pi codex; do
+  command -v "$tool" &>/dev/null && echo "✓ $tool" || echo "✗ $tool"
+done
+
+# roll-peer skill
+ls ~/.roll/skills/roll-peer/SKILL.md 2>/dev/null || echo "missing"
+```
+
+Check:
+- `~/.roll/.peer-state/` exists and is writable
+- `~/.roll/config.yaml` contains `peer_call_timeout` (default: 180)
+- At least one peer CLI (claude / kimi / pi) is installed
+- `roll-peer` skill exists
+
+## Report Format
+
+```
+🔬 Roll Doctor Report
+
+[✓/✗] Roll installation
+[✓/✗] Skills (N skills checked)
+[✓/✗] Symlinks (N tools checked)
+[✓/✗] Conventions sync
+[✓/✗] Templates integrity
+[✓/✗] Config
+[✓/✗] Peer Review
+
+---
+Issues found: N
+
+1. [severity] description → fix command
+2. [severity] description → fix command
+
+Recommendation: ...
+```
+
+## Severity Levels
+
+| Level | Meaning | Example |
+|-------|---------|---------|
+| 🔴 Critical | Skill completely broken | Broken symlink, missing SKILL.md |
+| 🟡 Warning | Partial functionality | Stale convention, outdated roll.md |
+| 🟢 Info | Recommendations | Missing optional tool symlink |
+
+## Auto-Fix
+
+If user confirms, automatically fix safe issues:
+
+- **Broken/missing symlinks** → `roll setup` (recreates all)
+- **Stale conventions** → `roll sync conventions`
+- **Missing template files** → warn user to re-install
+
+Never auto-fix without user confirmation for:
+- Overwriting `~/.claude/CLAUDE.md` (may have user customizations)
+- Deleting files
+
+## Quick Fix Commands
+
+```bash
+# Recreate all symlinks and sync conventions
+roll setup
+
+# Sync only conventions
+roll sync conventions
+
+# Reinstall (nuclear option)
+curl -fsSL https://raw.githubusercontent.com/seanyao/roll/main/install.sh | bash
+```

package/skills/roll-fix/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: roll-fix
+license: MIT
+allowed-tools: "Read, Edit, Write, Glob, Grep, Bash, Skill"
+description: "Load when the user provides a FIX-XXX or BUG-XXX item, or asks for a focused hotfix/bugfix through Roll lighter TCR repair workflow."
+---
+# Roll Fix
+
+This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
+
+## Load
+
+Load when the user provides a FIX-XXX or BUG-XXX item, or asks for a focused hotfix/bugfix through Roll lighter TCR repair workflow.
+
+## When Not to Use
+
+- Broad feature delivery; load roll-build.
+- Discussion-only design work; load roll-design.
+
+## Read On Demand
+
+- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
+- Keep this hub in context for trigger boundaries and hard gates.
+
+## Workflow Skeleton
+
+1. Read the FIX/BUG row and root-cause context.
+2. Reproduce or explain why reproduction is impossible.
+3. Add the failing/regression test first.
+4. Patch through TCR, run focused and local CI checks.
+5. Self-review, update backlog/evidence, and open PR.
+
+## Hard Gates
+
+- Every fix gets a regression signal or documented exception.
+- Blocking review findings are fixed in another TCR cycle.
+- The Review Score is produced by the runner's fresh-session peer Reviewer — the agent does NOT self-score.
+- Docs/code/product alignment is a DoD gate: user-visible behavior, command, output-copy, site, or delivery-view changes update the touched README/docs/guide/site/help in the same delivery.
+
+## Gotchas
+
+- Use for narrow FIX/BUG work; broad feature delivery belongs in roll-build.
+- Never patch without a regression signal or explicit reason why the bug cannot be reproduced locally.
+
+## Maintenance
+
+- Description changes require updates in `route-cases/skills.json`.
+- New observed failures should add a gotcha and the matching positive or negative route case.
+- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.