tzachbon/smart-ralph / plugins/ralph-specum-codex/skills/ralph-specum-refactor
ralph-specum-refactor
VerifiedThis skill should be used only when the user explicitly asks to use `$ralph-specum-refactor`, or explicitly asks Ralph Specum in Codex to revise spec artifacts after implementation learnings.
Ralph Specum Refactor
You are a coordinator, not a refactor specialist -- delegate spec revision to a refactor-specialist sub-agent.
Contract
- Resolve the active spec by explicit path, exact name, or
.current-spec - Review files in order:
requirements.md,design.md,tasks.md - Cascade downstream updates when upstream content changes
- Reconcile
activePrototypesand preserve unrelated refactor work
Action
- Resolve the target spec.
- Read
.progress.mdand existing spec files. - Run
prototype_records.py reconcilewhenever.ralph-state.jsonexists, including whenactivePrototypesis empty, then runselect-downstream --state "$BASE_PATH/.ralph-state.json" --target "$FILE" --path "$FILE"with the resolvedbasePath. Stop a file's refactor when itstargetDecisionsentry is not bothproofAvailable: trueandeligible: true, including an active blocker, stale dependency, approved-transfer overlap, or unavailable proof. - When refactor returns to execution, restore
taskIndexfrom the blocking entry'sreturnTaskIndexthroughmerge_state.pybefore dispatch. - Delegate spec revision to a
refactor-specialistsub-agent. Pass.progress.md, existing spec files, and implementation learnings. The sub-agent identifies what changed, what stayed accurate, and what is obsolete. Do NOT revise spec files yourself. - The sub-agent preserves newer Ralph concepts already expressed in the spec, including approval checkpoints, granularity choices,
[P]tasks,[VERIFY]tasks, VE tasks, and epic constraints when relevant. - The sub-agent updates files in order:
requirements.mddesign.mdtasks.md
- If requirements changed, revisit design and tasks.
- If design changed, revisit tasks.
- Record the rationale and cascade decisions in
.progress.md.
Response Handoff
- After revising spec files, name the files that changed and summarize the updates briefly.
- End with exactly one explicit choice prompt:
approve current artifactrequest changescontinue to implementation
- Treat
continue to implementationas approval of the updated spec files.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |