update-spec

To document implementation learnings into executable code-specs, you add a new entry to .trellis/spec/backend/ files. This enforces recording scope, signatures, contracts, validation matrices, and test points for recent code changes.

An executable code-spec after a bug fix should include scope, signatures, contracts, validation matrix, good/base/bad cases, and required tests. This ensures the implementation knowledge is specific, testable, and discoverable.

You need to update validation matrices and test points in documentation after feature implementation, bug fixes, design decisions, pattern discoveries, or infra cross-layer changes to prevent repeat mistakes and fragile assumptions.

To capture API request and response contracts for new features, record the expected payloads, env keys, and error behavior into .trellis/spec files. This maintains executable code-specs with concrete validation test points.

Yes, this code-spec process requires specific templates and a step-by-step update process. These mandatory templates ensure your knowledge capture under .trellis/spec/ remains specific, testable, and discoverable.

The best way to maintain documentation for cross-layer infra changes is enforcing executable code-specs with concrete signatures, payloads, env keys, validation matrices, and test points within your .trellis/spec files.