Service Implementation

Service Implementation

Purpose

Change production code within an agreed boundary and leave enough evidence for another engineer to verify the result.

Change context

• Read the assigned task, requirements, architecture notes, and write scope.
• Read the failing test and implementation contract from tdd-workflow when present.
• Read the recommendation from engineering-quality when the route includes maintainability or refactoring work.
• Inspect nearby code before choosing patterns.
• Confirm tests or validation commands before editing.
• Check for dirty files and avoid overwriting unrelated user changes.

Change method

1. Reproduce the current behavior or failure before editing when the task permits it.
2. Make the smallest coherent change that satisfies the acceptance criteria and failing test.
3. Reuse local patterns and dependencies. Add an abstraction only when it protects a real boundary or removes proven duplication.
4. Keep interface, data, migration, and backward-compatibility effects explicit.
5. Add or adjust a boundary or failure test if the existing contract could pass an incorrect implementation.
6. Run the narrow verification first, then the affected suite. Report any check that could not run and why.
7. Update the canonical documentation, runbook, ADR, or project note when behavior or operating steps change.

Engineering constraints

• Apply engineering-quality to new production code and focused refactors.
• Use current primary documentation before relying on external technology behavior. Context7 MCP is the preferred documentation source when available.
• Preserve dirty or unrelated files. Do not overwrite work that is outside the assigned scope.
• Obtain approval immediately before an irreversible, production-facing, costly, or security-sensitive action.
• Keep comments about hidden constraints and tradeoffs; let names and structure explain ordinary behavior.

Evidence

• Files and behavior changed
• Acceptance criteria satisfied
• Tests and validation commands with results
• Documentation or project memory updated
• Remaining risk, rollback, and deferred work

Ready when

• The diff stays within the stated write scope.
• The code has clear responsibilities, dependencies, side effects, and failure behavior.
• Existing behavior is preserved unless the requirement changes it explicitly.
• No test was weakened, skipped, or deleted merely to obtain a passing run.
• Validation evidence is reproducible.

Handoff

Hand off the changed files, test evidence, residual risk, rollback path, and documentation updates to qa-eval or pr-review.

References

• references/implementation-contract.md: Use this as the implementation handoff contract.