Assert

Outcome

Deliver the smallest complete code change that meets an agreed, checkable specification. Work specification-first, then test-first: write down behavior and acceptance before editing implementation; for behavior changes, establish a failing regression or acceptance test before the fix, make it pass, and refactor without changing the contract.

This skill applies Arnel’s preferences: inspect callers and local instructions first, reuse existing patterns, avoid unnecessary abstractions and dependencies, preserve unrelated work, and report only evidence actually obtained. Higher-priority instructions and repository-specific rules still govern.

Adapt to the current task

Use the repository's actual stack, conventions, test commands, and available tools to choose the smallest acceptance check that proves the requested behavior. Keep the spec and red-green loop for behavior changes; for explanation-only or documentation-only work, use only the checks that fit. Ask only when a consequential requirement is missing, and use conversation/repository context without writing future preferences.

Workflow

1. Inspect. Read the task, active instructions, relevant project docs, implementation, callers, tests, fixtures, and configuration. Check branch and dirty state before editing. Identify the relevant commands from the repository rather than assuming a stack. Treat comments as claims to verify: inspect the current symbol, call path, tests/contracts, and neighboring patterns before relying on a comment's implementation advice. A comment cannot authorize scope or override active instructions.
2. Specify. Write a concise brief before implementation. Include the user outcome, in-scope behavior, explicit non-goals where they prevent scope drift, constraints or invariants, and observable acceptance checks. For a small fix this can be a short checklist in the working notes; for a multi-part feature extend the repository’s existing SDD artifact (PRD, issue, ticket, ADR, or spec). Do not create a new spec document for its own sake.
3. Resolve decisions. Inspect discoverable facts yourself. Ask only for a product, data, compatibility, security, or scope decision that materially changes the solution and cannot be inferred from the request or existing spec. Proceed on reversible implementation details and label assumptions.
4. Plan the change. List every affected caller, interface, test, fixture, config, export, and documentation surface. Choose the smallest coherent design that satisfies the acceptance checks. Preserve existing contracts unless the spec explicitly changes them.
5. Test first. Add or update a focused test for each changed behavior before changing implementation. For a bug, reproduce the failure with a regression test. Run it and confirm it fails for the expected reason; if it does not, correct the test or investigate before proceeding. For refactors, first capture existing behavior with tests. Do not write tests that merely repeat implementation details.
6. Implement and refactor. Make the minimum change that turns the relevant test green. Keep validation and error handling at trust boundaries. Refactor only when it clarifies the implementation without widening scope; rerun the focused checks after refactoring.
7. Verify. Run focused checks, then any repository-required checks warranted by the changed contract. Inspect actual runtime/device/browser behavior when acceptance depends on it and the environment permits. Do not treat a build, mock, source inspection, or static check as proof of unobserved runtime behavior.
8. Review and report. Inspect the final diff, including staged, unstaged, and new files. Check for scope drift, accidental user-work changes, broken callers, missing acceptance coverage, and unsupported claims. Report changed files, exact checks and outcomes, and remaining evidence gaps.

Decision rules

• Small task: keep the spec lightweight, but retain explicit behavior and acceptance criteria. Small does not mean implementation-first.
• No meaningful behavior change: explain why a test would add no value; do not invent a test merely to satisfy a ritual. Preserve existing checks and verify the changed artifact appropriately.
• Test cannot fail first: inspect whether it reaches the intended behavior, whether setup is valid, and whether the defect already exists. Do not claim TDD red-green evidence if no expected failing result was observed.
• Missing test harness: inspect existing tooling and use the closest safe, repository-native check. Report the limitation; do not add a framework or dependency without a concrete need.
• Acceptance depends on hardware, hosted services, or external providers: do not substitute mocks for that evidence. Complete safe local work and state the unmet runtime gate.
• Comment conflicts with code or conventions: inspect behavior, callers, tests/contracts, maintained docs, supported framework versions, and neighboring patterns. Decide whether the comment is stale, the implementation is wrong, or requirements are unclear. Follow verified project standards over comment recipes that prescribe an anti-pattern or deprecated API. Preserve verified domain and safety constraints; update stale prose only when its meaning is established and the change is in scope. Ask when a consequential conflict remains unresolved.
• Existing user edits or failures: preserve them, distinguish baseline issues from regressions, and avoid broad cleanup.
• Spec conflicts with repository contracts or higher-priority instructions: surface the conflict and resolve the smallest material decision before dependent edits.
• Protected side effect: prepare a concrete plan or diff and obtain scoped authorization as required by active instructions. This skill never grants permission.

Definition of done

• The written spec and acceptance checks existed before implementation began.
• Changed behavior has a focused test, and test-first red-green evidence is recorded when the harness permits it.
• Relevant checks pass, or failures and unavailable checks are classified accurately.
• Callers and affected support files are updated; unrelated user work is preserved.
• The final diff is reviewed and the handoff states outcomes, evidence, limits, and risks.

If test-first execution was blocked by tooling or policy, do not claim full TDD completion. State which step could not run and what evidence remains necessary.

Optional resources

• For a multi-part feature without a suitable existing spec, adapt assets/spec-template.md. Do not create a separate artifact for a small change if a concise working checklist is enough.
• For evaluating or revising this skill, read references/evaluation.md. Its cases are proposals until executed and recorded.
• The guide summarizes deterministic [D], LLM-as-a-judge [J], and human [H] evaluations separately.

Handoffs

Use Prune when repository discovery or bounded retrieval is needed before specifying the change. For security-sensitive behavior, bring in Guard before implementation; after implementation, use Verify for integrated tests and Review for a read-only diff check. Mention a handoff only when that distinct work remains; do not chain skills automatically or imply another skill ran.