A spec doc written at sprint start and never touched again isn’t documentation — it’s archaeology. The structure that keeps a spec useful is a dedicated “current state” section that gets updated on every change and a change log that never gets edited.
At month 3, the Anchor email sequence engine was spec’d in a 4,000-word document. By month 7, when a new developer joined for a one-time project, that spec was so out of date it was actively misleading: 6 of the 12 named functions had been renamed, 2 had been deleted, and the trigger logic had been rewritten twice. The problem wasn’t the original spec. It was that nobody had a process for keeping it current.
The email sequence spec existed but had drifted. A developer reading it would spend more time figuring out what was still true than they would have spent reading the code directly. The solution wasn’t a better spec. It was a structure that makes updating the spec as frictionless as making the code change.
A spec doc that survives is narrow, has a clear “current state” section, and uses file paths and function names — not prose descriptions. The structure separates what’s true now from what used to be true:
# [Feature Name] — System Spec
**Last updated:** [DATE]
**Status:** Active / Deprecated / In migration
**Owner:** [Who maintains this doc]
## Current state (always current — update on every change)
What the system does RIGHT NOW. File paths, function names, option/meta keys.
No history here — that goes in the "change log" section.
- Entry point: `functions.php` → `[client]_register_sequences()`
- Trigger: `[client]_lead_created` action (fired from `[client]_create_lead()`)
- Sequence definitions: `[client]_get_sequence_definition( string $sequence_id ): array`
- Scheduler: `wp_schedule_single_event` per step, hook: `[client]_send_sequence_email`
- Storage: `[client]_sequence_enrollment` CPT, meta: `[client]_current_step`
## Configuration (what an operator needs to know)
Settings, option names, admin URLs. Anything non-obvious about operating the system.
## Known edge cases
Things that will bite a new developer if they don't know about them.
## Change log (append-only, newest first)
[2026-05-01] Sequence trigger moved from wp_insert_post to custom action.
[2026-04-10] Added conditional branching on [client]_lead_score meta.
[2026-03-22] Initial implementation.
The spec doc gets updated whenever any of these conditions occur. The update takes 5–10 minutes. Not updating it compounds into “this doc is useless” within 90 days:
Update the spec when:
1. A function listed in the spec is renamed, moved, or deleted
2. A trigger, hook, or storage key changes
3. A new edge case is discovered in production
4. A bug fix changes the spec'd behavior
5. An onboarding developer asks a question the spec doesn't answer
Spec docs live in the repository, not in Notion, Google Docs, or a wiki. When the code changes, the spec can be updated in the same commit. A spec that lives outside the repository drifts because the feedback loop is broken — the code change and the spec update happen in different systems, and the spec update is the one that gets skipped:
docs/
specs/
email-sequence-engine.md
lead-capture.md
inventory-sync.md
ai-wrapper.md
A spec doc that’s current is a force multiplier: it lets a second developer understand the system in 20 minutes instead of 2 hours of code reading. It lets you safely hand off a subsystem for one-off changes without a full briefing. The difference is between “here’s the doc” and “let me walk you through how it works from scratch.”
The “current state” section discipline is the key. Most spec docs fail because they mix current state, historical context, and future plans together. A reader can’t tell what’s true right now. A dedicated current-state section that gets updated on every change is always the accurate answer to “how does this work?”
System spec for the email sequence engine: 14 updates in 14 months, always within 24 hours of the change that triggered the update. When a second developer joined for a 2-day project at month 11, their onboarding to the email system took 25 minutes — they read the spec and had 3 questions, all answered by the edge cases section. The spec has been touched on 23 of 58 weeks since launch.
[client]_lead_source_tax taxonomy, set in [client]_create_lead().” The specific reference is navigable; the prose description is not.Every lesson stays free — no account, no paywall, no email gate, ever. But if you’d rather have this system standing on your business than wire all 48 lessons yourself, leave your email. We’ll send you a direct line to a build — and you’ll be first to hear when we add new tools to the curriculum.
None of this gates a single lesson. The curriculum was free before you got here and it stays that way.
You came here to understand the system, and now you do. If you’d rather have it standing on your business than spend the next three months wiring it yourself, GAP Concierge is the same architecture from these lessons — a white-label AI agent that knows your catalog and captures your leads — set up for you, from $97/mo.
See GAP Concierge →