global-skills/skills/spec/references/format.md

SPEC.md Canonical Format Specification

SPEC.md is the single source of truth for Spec-Driven Development (SDD). All sections are written in Caveman encoding.

---

1. Document Sections

§G — Goal

One single line in Caveman dialect stating the product intent.

# §G
build distributed rate limiter with sliding-window Redis Lua script.

§C — Constraints

Hard constraints, technology stack limits, and explicit out-of-scope declarations.

# §C
- Go 1.22+ stdlib + go-redis/v9.
- ⊥ external dependencies outside Redis.
- memory overhead ≤ 50MB @ 100k keys.
- out of scope: clustering, dynamic cluster topology changes.

§I — Interfaces

Public membranes: CLI commands, API endpoints, environment variables, or exported signatures.

# §I
api: POST /v1/limiter/check → 200 {allowed:bool, remaining:int, reset_ms:int}
cmd: `limiter-cli bench --rate=<n>` → stdout benchmark summary
env: REDIS_URL ! set

§R — Research Log (Optional)

Distilled external facts, primary documentation links, or RFC references.

# §R
id|domain|finding|source
R1|redis lua|reclaim memory via `redis.replicate_commands()`|redis.io/docs/manual/programmability/lua-api
R2|token bucket|GCRA algorithm reduces atomic roundtrips to 1|en.wikipedia.org/wiki/Generic_cell_rate_algorithm

§V — Invariants

Non-negotiable behavioral invariants. Numbered monotonically V1, V2, ...

# §V
V1: ∀ check req → atomic sliding window evaluate in Redis Lua
V2: Redis down → fail open (return allowed:true with header warning)
V3: latency p99 ≤ 2ms @ 10k rps

§T — Tasks

Ordered pipe table of implementation tasks. Numbered T1, T2, ...

• Status: . todo, ~ wip, x done.
• cites: Invariants (V<n>) or Interfaces (I.<name>) that the task must satisfy.

# §T
id|status|task|cites
T1|x|scaffold Redis client with fallback|V2,I.api
T2|~|implement sliding window Lua script|V1
T3|.|expose HTTP endpoint & healthcheck|I.api

§B — Bug Log

Feedback memory capturing bugs and regressions found during build/check/production.

# §B
id|date|cause|fix
B1|2026-04-20|lua script script error on empty redis key|V1

---

2. Sectioned Ownership

• spec is the sole mutator of SPEC.md.
• build flips only task status (. → ~ → x).
• check is strictly read-only.
• backprop appends §B rows and drafts §V lines.