---

name: engineering description: >- How to approach building and changing software: research before writing, plan, TDD, the work/right/fast progression, documentation hierarchy, fail-fast validation, and what to do when stuck. Use before implementing a feature, refactoring, fixing a bug, reviewing a change, or planning non-trivial repository work. Skip for content edits, prose, and Company OS data.

Engineering

Readability and changeability are primary. Small functions, single responsibility. Reserve mocks for isolated test seams.

Research before writing

• Use Grep/Glob to map the space. Read files end-to-end when you will edit them, plus immediate callers and tests.

Conform before creating

• Before adding new code, find 2-3 examples of similar code in the codebase. Match their naming, file structure, error handling, and test style.
• Priority: architecture docs (CLAUDE.md, rules) outrank existing code. Documented intent wins when current code contradicts it.
• Without a target doc, follow established codebase conventions. Consistency beats personal preference.

Plan

• Enter plan mode for non-trivial tasks (3+ steps, architectural decisions, verification work).
• Plan at two levels: high-level (overall goals and flow), then task-level (specific files or features). Implement only after the user approves both levels.
• Before planning anything complex, list every source document, methodology file, and reference you intend to use. Wait for the user to add or remove items before producing the plan.
• When something goes sideways mid-execution, stop and re-plan.

Test-driven development (default)

Follow RED-GREEN-REFACTOR for new features and non-trivial logic:

1. RED: write a concrete failing test that defines the requirement.
2. GREEN: write the minimum code to make it pass.
3. REFACTOR: clean up via /simplify and /code-review high while keeping tests green.

TDD applies to features and non-trivial logic in real projects. Scripts, spikes, one-off tools, config tweaks, doc edits, typo fixes, and one-line changes skip the cycle and get the minimal runnable check instead. Use judgment.

Progression

1. Make it work: functioning code that passes tests.
2. Make it right: refactor for clarity and maintainability.
3. Make it fast: optimize only after profiling reveals a real bottleneck.

One feature at a time

• Finish one well-defined feature before the next. Defer nice-to-haves until the core is complete and verified.
• Completion chain: tests pass -> integration works end-to-end -> /simplify -> /code-review high. Run /simplify before the final summary on any task touching 3+ files or refactoring a non-trivial module. For auth/data/billing/external-API changes, add security and performance checks against baseline.
• Fix broken links in the chain before moving on.
• Cleanup, review, and quality passes scan the whole working tree (git status + git diff), not only files touched in the current conversation. In-flight changes from another session sit alongside today's work: read them for context and leave them to their author. An unstaged change you revert is gone from git for good.

Fail fast and validate

• Validate aggressively at inputs and integration boundaries. Give clear, descriptive errors when something breaks.
• Actively probe edge cases, invalid inputs, and unexpected conditions.

When not to be lazy

Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics. Work that doesn't warrant full TDD still leaves one runnable check behind: the smallest thing that fails if the logic breaks. Trivial one-liners need no test. YAGNI applies to tests too.

Comments and documentation

Deletion is the default. Write a comment only for a fact the code cannot state: an ordering constraint, an external limit or quirk, a security rationale, the bug a guard exists for, or a cross-file contract nothing else records. One sentence, in the file's prevailing style. Keep directive comments (shellcheck, eslint, noqa, pragma, shebang).

Documentation hierarchy, in order of preference:

1. Working code: self-documenting through clear naming.
2. Tests: executable documentation; the tests are the spec.
3. README / docs: setup, architecture, API specs.
4. Comments: last resort.

Leave it better

• Leave it better than you found it, even when fixing something unrelated.
• Clean up test scripts, data files, temporary backups, and files from abandoned strategies when done.

When stuck: STOP -> INVESTIGATE -> SIMPLIFY -> CLARIFY -> SEARCH

1. STOP: more code won't fix it. Re-plan.
2. INVESTIGATE: use a debugger, add logging, inspect actual I/O.
3. SIMPLIFY: isolate the problem with a smaller test.
4. CLARIFY: ask before guessing at requirements.
5. SEARCH: look for existing solutions in this codebase or elsewhere.

After 3 distinct investigation attempts without progress, escalate with: goal, attempts, actual vs expected, environment state, next steps needed.

Autonomous bug fixing

Given a clear bug report: fix it. Errors, logs, failing tests point the way. Fix failing CI without waiting to be told how. Ask for clarification when the requirement contradicts itself, references a missing artifact, or has more than one defensible interpretation. Otherwise proceed.