| name | repo-process-doctor |
| description | Audit existing repositories for agent-workflow drift and repair opportunities. Use when a repo has custom agents, commands, process docs, or ticket systems and you need to diagnose contradictory status semantics, raw-file stage control, missing workflow-state tools, unsafe read-only delegation, or other workflow smells. Do not use for setting up a new repo (use scaffold-kickoff) or when issues are with code logic, not process. |
Repo Process Doctor
Use this skill to inspect and repair agent-workflow issues in an existing repository.
Modes
- audit — Report findings only. Use for initial inspection or post-scaffold verification.
- propose-repair — Write a repair plan for user approval. Use when unsure if repairs change project intent.
- apply-repair — Apply repairs directly. Use when findings are clearly safe to fix.
Procedure
1. Inventory process artifacts
Scan for all process-related files:
find . -name "AGENTS.md" -o -name "BOARD.md" -o -name "manifest.json" -path "*/tickets/*" \
-o -name "workflow*.json" -o -name "*.yaml" -path "*agents*" \
-o -name "*.md" -path "*/tickets/*" 2>/dev/null
2. Check for workflow smells
Contradictory status semantics — Different files define different status values.
grep -r "status:" tickets/ docs/ AGENTS.md 2>/dev/null | sort -u
Red flag: "done" vs "completed" vs "closed" in different files.
Missing state tools — Tickets exist but no tools to read/update them programmatically.
ls **/tools/*ticket* **/tools/*state* **/tools/*status* 2>/dev/null
Unsafe read-only delegation — Read-only agents with write permissions or write tasks.
grep -r "permissions:" **/agents/ 2>/dev/null
grep -rn "write\|edit\|create\|modify" **/agents/*review* **/agents/*research* 2>/dev/null
Orphaned tickets — In-progress tickets with no recent activity.
Circular dependencies — Tickets that depend on each other.
Stale board — BOARD.md older than latest ticket modification.
Raw-file stage control — Agents editing state files directly instead of using tools.
3. Generate diagnosis report
# Process Doctor Report
Generated: [timestamp]
## Summary
- Files scanned: N
- Issues found: N (X critical, Y warnings)
## Critical Issues
| Issue | Location | Impact | Fix |
|-------|----------|--------|-----|
| [smell name] | [file] | [what breaks] | [safer pattern] |
## Warnings
| Issue | Location | Recommendation |
|-------|----------|----------------|
| [smell name] | [file] | [suggestion] |
## Health Score
[GREEN | YELLOW | RED] — [explanation]
4. Choose repair approach
Safe repairs (apply directly):
- Regenerating derived docs (BOARD.md) from canonical state (manifest)
- Aligning status values to canonical set
- Removing raw-file stage control where tool-backed alternatives exist
- Fixing read-only agents that have mutating permissions
- Normalizing contradictory status semantics
Intent-changing repairs (escalate to user):
- Changes that affect project scope or product intent
- Choosing between unresolved stack/runtime options
- Changing provider or model choices
- Deleting or rewriting curated human decisions
5. Apply repairs (if in apply-repair mode)
For each safe repair:
- Read the finding and identify the safer pattern
- Apply the fix
- Verify the change resolves the finding
- Leave an obvious repair trail (document what was changed and why)
For each intent-changing repair:
- Present the finding and proposed repair to the user
- Explain why this might change project intent
- Wait for user decision before proceeding
6. Post-repair verification
Re-run the audit to confirm findings are resolved. All safe repairs should produce a clean pass.
Output contract
- Concise diagnosis of each finding with root cause
- Chosen mode (audit / propose-repair / apply-repair)
- Exact files patched (if apply-repair)
- Target safer pattern for each repair
- Post-repair verification results
Rules
- Do not preserve contradictory status semantics just because they already exist
- Do not keep multi-surface workflow state if one surface can become derived
- Treat read-only mutation paths as blockers
- Default to apply-repair for safe repairs, escalate intent-changing repairs
- Always leave an obvious repair trail — never silently fix without evidence
- Do not leave a repo in a mixed old/new workflow state
Failure handling
- No process artifacts found: Report "No agent infrastructure detected. Use scaffold-kickoff to create."
- Conflicts in repair: If auto-fix would lose data, stop and list conflicting files for manual resolution
- Unable to parse ticket format: Flag specific files as malformed, continue with parseable files
References
- This is step 8 of the scaffold-kickoff flow — continue to
../handoff-brief/SKILL.md
- Complements scaffold-kickoff: kickoff creates, doctor maintains
