update-spec

You can preserve implementation knowledge by updating .trellis/spec/ documents with executable code-spec contracts. This captures concrete signatures, validation behavior, and error matrices so future AI runs execute consistently and safely.

Documenting infrastructure and cross-layer changes requires a deeper spec structure. You should record scope, triggers, signatures, validation matrices, and test points to ensure changes remain verifiable and reduce future mis-execution.

You should update executable specs immediately after implementing features, fixing bugs, or making design decisions. This ensures the spec files contain required contracts, assertion points, and wrong vs correct examples while the context is fresh.

Structure validation matrices by including scope/trigger, signatures, contracts, error handling, good/base/bad cases, and required tests with assertion points. This ensures the code-spec files remain verifiable and executable over time.

Yes, this approach supports adding design decisions, conventions, patterns, anti-patterns, gotchas, and common mistakes. Recording them in the correct spec location ensures future development avoids repeating documented errors.

Execution often fails because implementation knowledge was lost in chat rather than captured as executable contracts. Without updated spec files containing validation behavior and error matrices, future runs lack the required context for consistency.