Update Code-Spec - Capture Executable Contracts

When you learn something valuable (from debugging, implementing, or discussion), use this 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:

1. Scope / Trigger
2. Signatures (command/API/DB)
3. Contracts (request/response/env)
4. Validation & Error Matrix
5. Good/Base/Bad Cases
6. Tests Required (with assertion points)
7. Wrong vs Correct (at least one pair)

---

When to Update Code-Specs

Trigger	Example	Target Spec
Implemented a feature	Added a new integration or module	Relevant spec file
Made a design decision	Chose extensibility pattern over simplicity	Relevant spec + "Design Decisions" section
Fixed a bug	Found a subtle issue with error handling	Relevant spec (e.g., error-handling docs)
Discovered a pattern	Found a better way to structure code	Relevant spec file
Hit a gotcha	Learned that X must be done before Y	Relevant spec + "Common Mistakes" section
Established a convention	Team agreed on naming pattern	Quality guidelines
New thinking trigger	"Don't forget to check X before doing Y"	guides/*.md (as a checklist item)

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/
├── <layer>/           # Per-layer coding standards (e.g., backend/, frontend/, api/)
│   ├── 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	<layer>/*.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 a spec layer directory
• "This is what to consider before writing" → Put in guides/

Example:

Learning	Wrong Location	Correct Location
"Use API X not API Y for this task"	❌ guides/ (too specific for a thinking guide)	✅ Relevant spec file (concrete convention)
"Remember to check X when doing Y"	❌ Spec file (too abstract for a spec)	✅ guides/ (thinking checklist)

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:

1. What did you learn? (Be specific)
2. Why is it important? (What problem does it prevent?)
3. 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:

1. Be Specific: Include concrete examples, not just abstract rules
2. Explain Why: State the problem this prevents
3. Show Contracts: Add signatures, payload fields, and error behavior
4. Show Code: Add code snippets for key patterns
5. 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:

1. What did you just finish?

   • Fixed a bug
   • Implemented a feature
   • Refactored code
   • Had a discussion about approach

2. 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)

3. 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

4. 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 → `update-spec` (Trellis command) → Knowledge captured
       ↑                                  ↓
  `break-loop` (Trellis command) ←──────────────────── Future sessions benefit
  (deep bug analysis)

• ``break-loop (Trellis command) - Analyzes bugs deeply, often reveals spec updates needed
• ``update-spec (Trellis command) - Actually makes the updates
• ``finish-work (Trellis command) - 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