Coding Workflow
A Research → Plan → User Review → Implement 4-stage procedure for code change tasks.
Trivial tasks such as simple configuration changes or 1~2 line edits may skip this workflow.
Step-by-Step Procedure
Step 1: Research (Read the Codebase)
Read and understand the relevant code deeply, then write findings to .ralph/docs/generated/research-<task>.md.
- Do not skim a file and move on at the signature level
- Understand existing layers, ORM relationships, and duplicate API presence
- Mandatory exploration of existing test files: Find related
*.test.*,*.spec.*files and understand what cases are already covered - Do not summarize in chat — always write to a file
Step 2: Plan (Write Plan MD)
Write a detailed implementation plan in .ralph/docs/generated/plan-<task>.md.
Include:
- Detailed description of the approach
- Code snippets showing actual changes
- List of file paths to be modified
- Considerations / trade-offs
- Verification plan (required): For each change group, specify verification procedure, command/URL, and expected result
Step 3: User Review
After writing the plan MD, report STATUS: BLOCKED and wait for user review.
Report content:
- Plan file path:
.ralph/docs/generated/plan-<task>.md - Number of changed files, summary of modification scope
Items for the user to verify:
- Is the approach appropriate?
- Is the modification scope within the issue/PR scope?
- Does it match existing patterns/conventions?
On user feedback → revise plan and re-review. On approval → proceed to step 4.
Step 4: Implement (TDD applied by default)
Once the plan is approved, implement using the tdd skill's cycle topic (Red→Green→Refactor). After implementation, run tests using the tdd skill's run topic and report results.
TDD opt-out: If the user specifies --no-tdd, implement without tests.
Commit after implementation: If build + tests pass, proceed to commit. Do not ask the user whether to commit. If a related existing commit exists, confirm whether to amend via AskUserQuestion.
Other:
- Mark completed tasks/steps as
[x]in fix_plan.md - Do not stop until all steps are complete
- Do not use
unknowntypes - Continuously run type checks during implementation (
pnpm typecheckortsc --noEmit) - Do not introduce new type errors
When Going in the Wrong Direction
Do not patch over a bad approach — revert and restart with a narrower scope.
cmd /c git checkout -- <files> # revert changes
Revise the plan and restart from step 3 (user review).
Applicability by Task Complexity
| Task Complexity | Scope |
|---|---|
| trivial (1~2 line edits, config value changes) | Can be skipped — implement directly |
| moderate (3~10 files, logic changes) | Start from step 2 (plan) |
| complex (10+ files, new features, architecture changes) | Perform all steps from step 1 (research) |
Self-Improvement
After this skill invocation completes, self-improve based on the conversation:
- Detect limitations, failures, and workaround patterns for this skill in the conversation
- If improvement candidates are found, run
/skill-kit upgrade code-workflow