Skip to content

The 9-field item template

The whole project rests on this template. Every Mandatory item in every role file follows it. Workers that produce items missing fields are rejected at the quality gate. PRs that add items not following it are rejected in review.

The 9 fields

Every item carries:

  1. What exactly — the concrete pattern, with code where applicable. No slogans.
  2. Why mandatory (failure mode) — specific failure that occurs when omitted, with a real-world citation (postmortem, incident, public CVE).
  3. Minimum implementation — compileable code in the default stack (TypeScript/Node + Postgres) unless stack-specific.
  4. Failure modes of the minimum implementation — when the minimum breaks; trigger to upgrade.
  5. Validation method — concrete test or command that verifies the item is wired correctly.
  6. Why AI tools systematically miss this — the LLM-behavioral reason. The load-bearing innovation.
  7. Sources — >=2 Tier-1 primary citations from .planning/worker-briefings/_shared/source-tier-index.md.
  8. Cross-references — other items this depends on, conflicts with, or implies.
  9. Estimated time to retrofit — the cost if added later instead of Day 1.

The full template lives at .planning/worker-briefings/_shared/item-template.md and is the canonical spec for any contributor adding new items.

Worked example — Backend Item 1 (Idempotency-Key)

Here's an actual item from core/roles/backend.md showing all 9 fields populated:

### Item 1 — Idempotency-Key header on every state-changing route

Category: Mandatory
Triggers when: always

1. What exactly:
Every POST/PUT/PATCH/DELETE route accepts an `Idempotency-Key:
<client-generated-uuid>` request header. The server persists, keyed on
`(tenant_id, key_hash, route_hash)`, the response status, response headers
(allow-listed), response body, and a SHA-256 of the request body. TTL: 24
hours minimum. On a second request with the same key:
- Same body hash → return the stored status + body verbatim, with header
  `Idempotent-Replay: true`.
- Different body hash → 409 Conflict + Problem Details
  `type=urn:problem:idempotency-conflict`.
- In-flight (entry exists, response empty) → 409 Conflict
  `type=urn:problem:idempotency-in-progress`.
Scope is per-tenant (never global; collisions across tenants would leak
data). Keys are opaque strings — never derive the response from them.

2. Why mandatory (failure mode):
Network retries from mobile clients, browser-tab-double-clicks, queue
re-deliveries. Without an Idempotency-Key contract, the second delivery
charges the customer twice / creates a duplicate order / re-emits a
notification. Stripe shipped Idempotency-Key in 2014 specifically because
the failure mode is universal, not Stripe-specific.

3. Minimum implementation:
[~50 lines of TypeScript Express middleware showing key validation,
tenant-scoped storage, body-hash comparison, conflict response, in-flight
detection, and TTL handling.]

4. Failure modes of the minimum implementation:
- In-memory store overflows at >100k req/s; upgrade to Redis-backed key
  store at that scale.
- Single-instance store breaks horizontal scaling; promote to shared
  Postgres or Redis from day one if multi-replica.

5. Validation method:
Integration test: send the same POST twice with the same key → second
response carries `Idempotent-Replay: true` header and identical body.
Integration test: send the same key with a different body → 409 with
`urn:problem:idempotency-conflict` type.

6. Why AI tools systematically miss this:
Underrepresentation in training data (RFC headers like Idempotency-Key are
rare in tutorials) + path-of-least-resistance bias (the middleware is
~50 lines, the no-op alternative is zero lines). LLMs default to "just
retry the call" without the contract.

7. Sources:
- Stripe Engineering: "Designing robust and predictable APIs with
  idempotency" (Brandur Leach, 2017) — primary
- IETF RFC 9457 §4 (Problem Details for HTTP APIs, error response shape)
- IETF draft-ietf-httpapi-idempotency-key-header-06

8. Cross-references:
- architect.md Item 8 (Idempotency as architectural commitment)
- security.md Item 29 (HMAC verification on inbound webhooks — the
  webhook-receiver flavor of the same pattern)

9. Estimated time to retrofit:
2-4 days for a project with <50k user records; weeks for >500k users due
to backfill complexity for in-flight payments and the integration-partner
key-rotation negotiation.

Why field 6 is the load-bearing one

Fields 1–5 and 7–9 exist in some form across the canonical references — OWASP ASVS, the AWS Well-Architected Framework, the 12-Factor App, the SRE Book. They're the what and why of senior engineering practice.

Field 6 — why AI tools systematically miss this — does not exist anywhere else. It's what turns the item from a generic rule into context that changes the LLM's plan output. Examples of the categories field 6 reaches for:

  • Underrepresentation in training data. RFC headers, distributed-systems patterns, security primitives that exist in standards docs but not in tutorial blog posts.
  • Path-of-least-resistance bias. The middleware is 50 lines; the no-op alternative is 0 lines. LLMs default to the shorter path.
  • Outdated patterns dominate the corpus. Session-cookie auth in tutorials beats OAuth 2.1 PKCE in standards. The model fluently reproduces the deprecated pattern.
  • Subjectivity assumed where it doesn't exist. "Add structured logging" sounds like a style choice, not a Mandatory item — so the model treats it as optional.
  • Plausible failure modes are absent from prompts. No one prompts "and make sure the regex doesn't catastrophic-backtrack" because they didn't know to. The model generates the regex without the resource limit.

Without field 6, the item is one more "best practice" the planner can deprioritize. With field 6, the planner has a reason the item must surface even when the user didn't ask.

The 7 cross-cutting LLM-failure-mode categories are documented in core/anti-patterns.md.

Quality bar for a new item

A PR proposing a new item must:

  1. Fill all 9 fields (no TODO, no "see also").
  2. Cite >=2 Tier-1 primary sources (Tier 2 may supplement, never replace; see Source Tier System).
  3. Map field 6 to one of the 7 categories in core/anti-patterns.md — generic field 6 is rejected.
  4. Include cross-references to existing items if they exist (no orphan items).
  5. Pass the validator: python .github/scripts/validate-items.py.
  6. End with the <!-- ITEM-N COMPLETE --> marker (used by parsers).

See Adding Items for the contribution workflow.

Item categories

Every item carries one of three categories:

  • Mandatory — applies in every project that activates the role. The 314 number refers to Mandatory items (314 across all roles before profile filtering).
  • Conditional — applies only when a named trigger is true. Example: WCAG-AA conformance triggers when the product is sold to a public-sector buyer or operated in a regulated industry.
  • Flag-and-Defer — known to matter but acknowledged as deferred for V1, with the named trigger that should re-open it. Used for Mobile-Engineer-role items in mobile-app profile, ML-Engineer items in ai-wrapper, etc.

Profile filtering reduces the active subset (e.g., 264 active in b2b-saas-web, 184 in internal-tool) but never weakens the per-item bar. An internal tool still needs idempotency on state-changing routes, just like a B2B SaaS.

Where the template comes from

The 9-field shape was set during Phase 1 of the V1.0 build — explicitly anti-fragile against the failure modes documented in core/anti-patterns.md. The shape evolved through three iterations as workers produced role files and gaps were caught in Phase 3 adversarial review. The Phase-3 audit found 21 cross-cutting gaps; all 21 were patched into the role files before Phase 4 synthesis. See Brain-Worker Pattern for the full build narrative.