Knowledge Flywheel

Step 5: The Nap (Critical Non-Automated Step)

After execution, before starting the next cycle:

1. Create learnings.md in spec directory

   # Implementation Learnings — Spec 005
   
   ## Implementation Insights
   - What worked well
   - What didn't work
   - Edge cases discovered
   
   ## Reusable Patterns
   - New patterns that generalize beyond this feature
   
   ## Architecture Observations
   - Layer discipline validated or violated
   
   ## Process Observations
   - Planning vs execution ratio
   - Review cycle efficiency
   
   ## Recommendations for Future Specs
   - What to do differently next time
   

2. Update spec.md with Implementation Notes Add a section at the end of spec.md:

   ## Implementation Notes
   
   **Status:** ✅ Delivered (YYYY-MM-DD)
   
   **Actual vs Planned:**
   - All 5 user stories delivered
   - Deviations: [list key differences]
   
   **Key Learnings:**
   - [Summarize top 3-5 learnings]
   - See [learnings.md](./learnings.md) for full details
   
   **Process Metrics:**
   - 12 tasks across 3 phases
   - 75% first-review approval rate
   - 1.25 review cycles per PR
   

3. Commit both files — they are part of the spec artifact set

Step 6: Squask Sync (Automated Knowledge Propagation)

# After learnings.md exists, run sync
squask sync specs/005-hook-fixes-cli-polish

# What it does:
# 1. Reads specs/005-*/learnings.md
# 2. Reads .squad/agents/*/history.md (since last sync)
# 3. Appends new learnings to agent history files
# 4. Appends curated learnings to .specify/memory/constitution.md
# 5. Updates constitution version (1.0.0 → 1.1.0) + Last Amended date
# 6. Writes sync state to .squad/.sync-state (idempotent, prevents duplicates)

Sync state tracking (idempotent):

{
  "lastSync": "2025-03-24T14:32:00.000Z",
  "syncedSpecs": ["005-hook-fixes-cli-polish"],
  "syncedFingerprints": ["hash1", "hash2"]
}

Re-running sync on the same spec is safe — fingerprints prevent duplicate entries.

Constitution Amendment Protocol (Part of Sync)

When sync writes to constitution:

**Version**: 1.1.0 | **Last Amended**: 2025-03-24

## Learnings from 005-hook-fixes-cli-polish

### Exit Code Contract Violation Pattern
Contracts without automated tests are documentation, not enforcement.
PR #328 regression (exit 0 → exit 1) violated graceful-failure contract.
Solution: Add contract-specific tests (T004).

### Git Permissions Dual-Track
Executable permissions need both `chmod +x` (filesystem) AND 
`git update-index --chmod=+x` (git index) for clone persistence.

Version bumps:

• Minor bump (1.0.0 → 1.1.0): New learnings added
• Major bump (1.x.x → 2.0.0): Breaking principle changes (rare)
• Patch bump (never): Constitution uses major.minor.0 only

Pre-Specify Context Injection

Before starting a new spec cycle, generate context:

# Generate squad-context.md for the next feature
squask context specs/006-new-feature

# What it includes:
# - Team Skills (highest signal)
# - Relevant Decisions (filtered for recency)
# - Agent Learnings (from history files, summarized)
# - Previous Spec Learnings (from learnings.md files)

Then run /speckit.specify — it will see squad-context.md and use it as context.

Examples

Full Flywheel Execution (Spec 005 → Spec 006)

# Spec 005 execution complete, PRs merged

# Step 5: Nap
vim specs/005-hook-fixes-cli-polish/learnings.md
# ... document insights, patterns, recommendations ...
vim specs/005-hook-fixes-cli-polish/spec.md
# ... add Implementation Notes section ...
git commit -m "chore: spec 005 learnings synthesis"

# Step 6: Sync
squask sync specs/005-hook-fixes-cli-polish
# Output:
# ✅ Synced 3 learnings to .squad/agents/richard/history.md
# ✅ Appended to .specify/memory/constitution.md (v1.0.0 → v1.1.0)
# ✅ Sync state saved (.squad/.sync-state)

# Next cycle starts
squask context specs/006-new-feature
# Output:
# ✅ Generated squad-context.md (8.2KB)
# - 4 skills (3.1KB)
# - 12 decisions (2.4KB)
# - 8 learnings (2.7KB)

# Now run SpecKit with enriched context
/speckit.specify "Add MCP server mode for bridge"
# SpecKit sees squad-context.md, uses it for planning
# Spec benefits from lessons learned in 005

Learnings File Template

# Implementation Learnings — Spec 005: Hook Fixes & CLI Polish

**Feature:** Hook exit codes, git permissions, CLI improvements  
**Cycle:** 2025-03-22 to 2025-03-24  
**Tasks:** 12 (T001-T012)  
**PRs:** 4 (all merged)  
**Test Coverage:** 843 tests passing

## Implementation Insights

### Exit Code Contract Violation Pattern
**What happened:** PR #328 changed hook exit code from 0 to 1, breaking graceful failure contract.  
**Why it matters:** Contracts without tests are just documentation.  
**Solution:** Add T004 (contract tests) to validate exit codes atomically.  
**Reusable:** Any contract (CLI, API, config) needs dedicated tests separate from functionality tests.

### Git Permissions Dual-Track
**What happened:** Hooks deployed but lost executable permissions on clone.  
**Root cause:** `chmod +x` modifies filesystem, not git index.  
**Solution:** `git update-index --chmod=+x` persists permissions in git.  
**Reusable:** All deployed scripts need both filesystem + git index permissions.

## Reusable Patterns

### Node.js Environment Check Pattern
```bash
if ! command -v node &>/dev/null; then
  echo "⚠️  Node.js not found — skipping hook" >&2
  exit 0  # Graceful degradation
fi

Config-Driven Hook Behavior

// BridgeConfig.hooks.autoCreateIssues: boolean
// Default to automation, provide config opt-out
if (config.hooks.autoCreateIssues) {
  await createIssues(tasks);
}

Architecture Observations

✅ Clean Architecture compliance validated
All changes in outer layers (adapters, CLI). Zero inner-layer modifications.
Layer discipline holds even under tight deadlines.

Process Observations

Parallel task execution: 60-70% time saved (T004+T006+T008 in parallel)
Comprehensive upfront spec: 75% first-review approval rate (9 of 12 PRs)
Issue auto-closure gap: Squash merge breaks GitHub auto-close (needs PR body preservation)

Recommendations for Future Specs

1. Design for actual workflow, not documented workflow — Hooks designed for CLI but used via agents
2. Test contracts atomically — Separate exit code tests from functionality tests
3. Git index permissions matter — Add to deployment checklist
4. Config flags > code changes — autoCreateIssues flag prevents breaking existing workflows
5. Exit 0 for graceful degradation — Missing dependencies should warn, not fail

## Anti-Patterns

- **Skipping the nap** — Going straight from execution to next spec loses learnings
- **Sync without learnings.md** — Only agent history is synced; spec-level insights lost
- **Manual constitution edits** — Use `squask sync`; it handles version bumping + deduplication
- **Duplicate sync runs without checking state** — Sync is idempotent, but check `.squad/.sync-state` first
- **Ignoring squad-context.md during planning** — The whole point of the flywheel is to use prior learnings
- **Creating learnings.md without updating spec.md** — Spec should have Implementation Notes linking to learnings
- **Version bump without Last Amended date** — Constitution amendment protocol requires both