engineering-discipline

Engineering Discipline

Apply on every coding, design, and documentation task. Pairs with the response-discipline skill (communication rules).

Docs first, never memory

For any external API, library, SDK, config format, or tool behavior:

1. Fetch the official documentation online BEFORE writing code. Training memory is stale and wrong for version-specific details.
2. One source is a claim, not a fact. Corroborate with the official/primary doc before building on it; unofficial mirrors and blogs are hints.
3. Never extend a doc claim past what it states. "No date params" says nothing about payload bounds — mark the gap as unmeasured, don't infer.
4. Plan the approach from what the docs actually say — endpoints, params, auth flow, limits.
5. Implement against the doc, not the recollection.

Maintain a doc ledger in the project root — docs-used.md (or .json if the project prefers):

• Append an entry every time a doc informs an implementation decision.
• Read the ledger at session start — re-verify against listed docs instead of re-assuming.
• If behavior looks wrong later, the ledger points to the exact doc to re-check.

Give each ledger entry an ID, and reference that ID in code at the point of use — @see in a JSDoc block for functions/constants (IDE-rendered), plain comment for lines inside a body:

| ID | Doc URL | Used in | Purpose | Date |
|---|---|---|---|---|
| D1 | https://developers.google.com/.../runReport | src/lib/ga4/client.ts | runReport request shape, quota limits | 2026-08-06 |

/**
 * @see docs-used.md#D1 — runReport caps: 10 metrics, 9 dimensions
 */
export async function fetchReport(...) {
  // docs-used.md#D2 — quota header only present on 429
  const remaining = res.headers['x-quota-remaining'];
}

URL lives only in the ledger — one place to update. Code carries just the ID for cross-checking.

Minimal code ladder

Before writing any code, stop at the first rung that holds:

1. Does this need to exist? → no: skip it (YAGNI)
2. Already in this codebase? → reuse, don't rewrite
3. Stdlib does it? → use it
4. Native platform feature? → use it
5. Installed dependency? → use it
6. One line? → one line
7. Only then: the minimum that works