Update Code-Spec - Capture Executable Contracts

When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents.

Timing: After completing a task, fixing a bug, or discovering a new pattern

Code-Spec First Rule (CRITICAL)

In this project, "spec" for implementation work means code-spec:

• Executable contracts (not principle-only text)

• Concrete signatures, payload fields, env keys, and boundary behavior

• Testable validation/error behavior

If the change touches infra or cross-layer contracts, code-spec depth is mandatory.

Mandatory Triggers

Apply code-spec depth when the change includes any of:

• New/changed command or API signature

• Cross-layer request/response contract change

• Database schema/migration change

• Infra integration (storage, queue, cache, secrets, env wiring)

Mandatory Output (7 Sections)

For triggered tasks, include all sections below:

• Scope / Trigger

• Signatures (command/API/DB)

• Contracts (request/response/env)

• Validation & Error Matrix

• Good/Base/Bad Cases

• Tests Required (with assertion points)

• Wrong vs Correct (at least one pair)

When to Update Code-Specs

Trigger Example Target Spec

Implemented a feature Added template download with giget Relevant backend/ or frontend/ file

Made a design decision Used type field + mapping table for extensibility Relevant code-spec + "Design Decisions" section

Fixed a bug Found a subtle issue with error handling backend/error-handling.md

Discovered a pattern Found a better way to structure code Relevant backend/ or frontend/ file

Hit a gotcha Learned that X must be done before Y Relevant code-spec + "Common Mistakes" section

Established a convention Team agreed on naming pattern quality-guidelines.md

New thinking trigger "Don't forget to check X before doing Y" guides/*.md (as a checklist item, not detailed rules)

Key Insight: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.

Spec Structure Overview

.trellis/spec/ ├── backend/ # Backend coding standards │ ├── index.md # Overview and links │ └── *.md # Topic-specific guidelines ├── frontend/ # Frontend coding standards │ ├── index.md # Overview and links │ └── *.md # Topic-specific guidelines └── guides/ # Thinking checklists (NOT coding specs!) ├── index.md # Guide index └── *.md # Topic-specific guides

CRITICAL: Code-Spec vs Guide - Know the Difference

Type Location Purpose Content Style

Code-Spec backend/.md , frontend/.md

Tell AI "how to implement safely" Signatures, contracts, matrices, cases, test points

Guide guides/*.md

Help AI "what to think about" Checklists, questions, pointers to specs

Decision Rule: Ask yourself:

• "This is how to write the code" → Put in backend/ or frontend/

• "This is what to consider before writing" → Put in guides/

Example:

Learning Wrong Location Correct Location

"Use reconfigure() not TextIOWrapper for Windows stdout" ❌ guides/cross-platform-thinking-guide.md

✅ backend/script-conventions.md

"Remember to check encoding when writing cross-platform code" ❌ backend/script-conventions.md

✅ guides/cross-platform-thinking-guide.md

Guides should be short checklists that point to specs, not duplicate the detailed rules.

Update Process

Step 1: Identify What You Learned

Answer these questions:

• What did you learn? (Be specific)

• Why is it important? (What problem does it prevent?)

• Where does it belong? (Which spec file?)

Step 2: Classify the Update Type

Type Description Action

Design Decision Why we chose approach X over Y Add to "Design Decisions" section

Project Convention How we do X in this project Add to relevant section with examples

New Pattern A reusable approach discovered Add to "Patterns" section

Forbidden Pattern Something that causes problems Add to "Anti-patterns" or "Don't" section

Common Mistake Easy-to-make error Add to "Common Mistakes" section

Convention Agreed-upon standard Add to relevant section

Gotcha Non-obvious behavior Add warning callout

Step 3: Read the Target Code-Spec

Before editing, read the current code-spec to:

• Understand existing structure

• Avoid duplicating content

• Find the right section for your update

cat .trellis/spec/<category>/<file>.md

Step 4: Make the Update

Follow these principles:

• Be Specific: Include concrete examples, not just abstract rules

• Explain Why: State the problem this prevents

• Show Contracts: Add signatures, payload fields, and error behavior

• Show Code: Add code snippets for key patterns

• Keep it Short: One concept per section

Step 5: Update the Index (if needed)

If you added a new section or the code-spec status changed, update the category's index.md .

Update Templates

Mandatory Template for Infra/Cross-Layer Work

Scenario: <name>

1. Scope / Trigger

• Trigger: <why this requires code-spec depth>

2. Signatures

• Backend command/API/DB signature(s)

3. Contracts

• Request fields (name, type, constraints)
• Response fields (name, type, constraints)
• Environment keys (required/optional)

4. Validation & Error Matrix

• <condition> -> <error>

5. Good/Base/Bad Cases

• Good: ...
• Base: ...
• Bad: ...

6. Tests Required

• Unit/Integration/E2E with assertion points

7. Wrong vs Correct

Wrong

...

Correct

...

Adding a Design Decision

Design Decision: [Decision Name]

Context: What problem were we solving?

Options Considered:

1. Option A - brief description
2. Option B - brief description

Decision: We chose Option X because...

Example: ```typescript // How it's implemented code example ```

Extensibility: How to extend this in the future...

Adding a Project Convention

Convention: [Convention Name]

What: Brief description of the convention.

Why: Why we do it this way in this project.

Example: ```typescript // How to follow this convention code example ```

Related: Links to related conventions or specs.

Adding a New Pattern

Pattern Name

Problem: What problem does this solve?

Solution: Brief description of the approach.

Example: ``` // Good code example

// Bad code example ```

Why: Explanation of why this works better.

Adding a Forbidden Pattern

Don't: Pattern Name

Problem: ``` // Don't do this bad code example ```

Why it's bad: Explanation of the issue.

Instead: ``` // Do this instead good code example ```

Adding a Common Mistake

Common Mistake: Description

Symptom: What goes wrong

Cause: Why this happens

Fix: How to correct it

Prevention: How to avoid it in the future

Adding a Gotcha

Warning: Brief description of the non-obvious behavior.

Details about when this happens and how to handle it.

Interactive Mode

If you're unsure what to update, answer these prompts:

What did you just finish?

• Fixed a bug

• Implemented a feature

• Refactored code

• Had a discussion about approach

What did you learn or decide?

• Design decision (why X over Y)

• Project convention (how we do X)

• Non-obvious behavior (gotcha)

• Better approach (pattern)

Would future AI/developers need to know this?

• To understand how the code works → Yes, update spec

• To maintain or extend the feature → Yes, update spec

• To avoid repeating mistakes → Yes, update spec

• Purely one-off implementation detail → Maybe skip

Which area does it relate to?

• Backend code

• Frontend code

• Cross-layer data flow

• Code organization/reuse

• Quality/testing

Quality Checklist

Before finishing your code-spec update:

• Is the content specific and actionable?

• Did you include a code example?

• Did you explain WHY, not just WHAT?

• Did you include executable signatures/contracts?

• Did you include validation and error matrix?

• Did you include Good/Base/Bad cases?

• Did you include required tests with assertion points?

• Is it in the right code-spec file?

• Does it duplicate existing content?

• Would a new team member understand it?

Relationship to Other Commands

Development Flow: Learn something → /trellis:update-spec → Knowledge captured ↑ ↓ /trellis:break-loop ←──────────────────── Future sessions benefit (deep bug analysis)

• /trellis:break-loop

• Analyzes bugs deeply, often reveals spec updates needed

• /trellis:update-spec

• Actually makes the updates (this command)

• /trellis:finish-work

• Reminds you to check if specs need updates

Core Philosophy

Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.

The goal is institutional memory:

• What one person learns, everyone benefits from

• What AI learns in one session, persists to future sessions

• Mistakes become documented guardrails