| name | engineering-practices |
| description | Language-agnostic development practices: disciplined refactoring, small reviewable changes, trunk-based delivery and DORA-style flow, dependency hygiene, verification-before-completion, and working-in-legacy-code strategy. Use when refactoring, structuring a change into commits/PRs, deciding branching or release flow, adding/upgrading dependencies, or closing out a task ("is this actually done?"). For test methodology use testing; for review checklists use code-review.
|
| allowed-tools | ["Read","Glob","Grep","Bash"] |
Engineering Practices
IRON LAW: A TASK IS DONE WHEN THE EVIDENCE SAYS SO — BUILT, TESTED,
VERIFIED AGAINST THE ORIGINAL REQUEST — NOT WHEN THE CODE IS WRITTEN.
Refactoring Discipline (catalog-based)
- Refactoring changes structure, never behavior — keep tests green at every
step; if there are no tests, write characterization tests first.
- Small named moves (extract function, inline, rename, move, replace
conditional with polymorphism) applied one at a time — not a big-bang
rewrite. Commit between moves.
- Never mix refactoring and behavior change in one commit/PR. Two PRs or
clearly separated commits.
- Rule of three: tolerate duplication twice; abstract on the third
occurrence — and only if the name conveys more than the code.
- Boy-scout in scope only: improve what the task touches; file follow-ups
for the rest (no opportunistic drive-by churn).
Change & Delivery Flow
- Small batches: a PR reviewable in ≤ ~15 minutes beats a 2,000-line drop.
Slice by behavior (see
planner task mode), not by file type.
- Trunk-based mindset: short-lived branches, integrate continuously; gate
incomplete features behind flags (and file the flag-removal follow-up).
- Commits: atomic, buildable, message states WHY; include the ticket ID when
the repo follows a ticket convention (see
project-conventions).
- Optimize the DORA four keys directionally: lead time, deploy frequency,
change-failure rate, time-to-restore — favor changes that improve flow
without hurting stability.
Dependency Hygiene
- Adding a dependency is an architectural decision: maintenance activity,
transitive surface, license, supply-chain posture (see
secure-coding).
- Prefer the standard library / platform; wrap third-party APIs you don't
control at module boundaries you do.
- Upgrades: one dependency per PR, changelog read, lockfile committed,
tests run.
Verification Before Completion (closing gate)
Before reporting any task as done:
- Re-read the original request — was THIS asked? Anything dropped?
- Build + full test pass (not just the new tests).
- Exercise the change once like a user (run it; for UI see
device-interaction / xcode-agentic validation loop).
- Diff review of your own change: leftovers, debug prints, dead code,
unrelated edits.
- State residual risks and follow-ups explicitly.
Rationalization Table (STOP signs)
| If you think… | Reality |
|---|
| "I'll refactor while I'm in here anyway" | Scope creep kills reviewability; file a follow-up |
| "The tests pass, ship it" | Tests prove what tests cover; verify the actual request |
| "One big PR is more efficient" | Review quality collapses; defects hide in bulk |
| "We'll remove the feature flag later" | Without a ticket, "later" is never |
| "A quick library will save time" | You just adopted its bugs, CVEs, and upgrade train |
Related Skills
| Need | Skill |
|---|
| Test methodology, characterization tests | testing |
| Review standards | code-review |
| Root-cause workflow for bugs | debugging |
| Task decomposition, execution contracts | planner |
| Secure dependency decisions | secure-coding |
| PR/commit documentation | work-docs |
