| name | ohc-coding-discipline |
| description | Anti-overengineering rules. Use when writing, reviewing, or refactoring code. Enforces surgical changes, explicit assumptions, minimal scope, and verifiable success criteria. Extended from Karpathy guidelines for team AI workflows.
|
| allowed-tools | Read Bash |
OHC Coding Discipline
Tradeoff: biases toward caution over speed.
For trivial one-liners, use judgment. For anything >15 minutes, apply in full.
Principle 1: Explicit Assumptions — Don't guess, ask
Before writing code, state assumptions explicitly:
- What does "done" look like? (specific, not "it works")
- What is the input shape and expected output?
- Are there edge cases not yet mentioned?
If the request has multiple plausible interpretations:
→ Present them. Don't pick silently.
→ Threshold: if >1 interpretation AND consequence is >15 min work → ask.
If a simpler path exists than what was asked:
→ Name it and ask permission before taking it.
If something is genuinely unclear:
→ Stop. Name what's unclear. Do not infer forward.
See references/assumption-protocol.md for decision tree.
Principle 2: Minimal Scope — No speculative features
Write the minimum code that solves the stated problem.
Forbidden without explicit request:
- Abstractions for single-use code
- Future-proofing
- Unrequested performance optimization
- Refactoring of unrelated code
- New patterns or conventions beyond the task
Test: can every changed line be traced back to the user's explicit request?
If not, remove it or ask first.
Unrelated issues: noticed bugs or tech debt outside scope:
→ Log to .ohc/notepad.md under "## Noticed (not in scope)"
→ Do NOT fix. Do NOT expand scope silently.
See references/scope-guard.md. Run scripts/scope-check.sh after each task.
Principle 3: Surgical Changes — Clean diffs
Remove only what YOUR changes made unused.
Do not remove pre-existing dead code, imports, or variables unless explicitly asked.
Small, logical commits:
- Each commit = one logical change
- Message explains WHY, not just WHAT
- Use structured trailer format from CLAUDE.md
The diff test: would a reviewer understand every changed line from the commit
message alone? If not: split the commit or improve the message.
See references/surgical-change.md for examples.
Principle 4: Goal-Driven Execution — Define success first
Before writing any code, state the success criterion:
Success: [specific, verifiable statement]
Invalid (not verifiable):
- "Tests pass" — which tests? how many?
- "The feature works" — how do you know?
Valid (verifiable):
- "All 23 auth.test.ts cases pass with 0 skips, coverage ≥80%"
- "curl localhost:3000/api/health returns 200 with {status:'ok'}"
Loop: write → test → read output → fix → test again.
Never claim done without reading the verification output yourself.
See references/success-criteria.md for templates by task type.
OHC Extension 1: Workflow Gate
For tasks estimated at >30 minutes:
- Confirm a plan exists in .ohc/plans/
- If no plan: run the PLAN workflow first
- Do NOT write code without an approved plan for large tasks
OHC Extension 2: Team Handoff Discipline
When finishing any work session:
- Update .ohc/notepad.md (see collaborator agent for format)
- Write for your teammate, not yourself
- Include: what done, what wasn't, blockers, gotchas, next steps
- Commit:
chore: update notepad for handoff
OHC Extension 3: Scope Verification
Before starting: read PROJECT.md conventions section.
After finishing: run bash skills/ohc-coding-discipline/scripts/scope-check.sh
Confirm output shows only files in the task scope.
OHC Extension 4: Architecture Language
When reviewing or refactoring structure, use precise architecture vocabulary:
module, interface, seam, adapter, depth, leverage, and locality.
Prefer deep modules: small interfaces that hide meaningful behavior.
See references/architecture-vocabulary.md before proposing structural changes.
