ohc-coding-discipline

---
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:
1. Confirm a plan exists in .ohc/plans/
2. If no plan: run the PLAN workflow first
3. Do NOT write code without an approved plan for large tasks

---

## OHC Extension 2: Team Handoff Discipline

When finishing any work session:
1. Update .ohc/notepad.md (see collaborator agent for format)
2. Write for your teammate, not yourself
3. Include: what done, what wasn't, blockers, gotchas, next steps
4. 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.