# SCARS — {{PROJECT_NAME}} hard-won failure memory

> **The "what not to repeat" file.** Every entry below is a scar: a mistake
> paid for in production blood — symptom → root cause → do NOT → do → file
> pointer → commit SHA. Read this **before** fixing a bug; if we paid for the
> lesson once, we don't pay again.
>
> **Reading order.** [`ATLAS.md`](ATLAS.md) (*where* things live) →
> **this file** (*what breaks*) → [`.agents/skill/{{PROJECT_NAME}}/SKILL.md`](.agents/skill/{{PROJECT_NAME}}/SKILL.md) (*how* to do tasks).
>
> **Anchors are stable and immutable.** Cite them from PR descriptions, commit
> messages, FAQ entries, and other agents' prompts. Renaming an anchor =
> creating a new one + a redirect. Add one with `atlas anchor add NAME "summary"`.

---

## Table of contents

**Process / hygiene** *(every project keeps these — customise as needed)*
- [§NO-COAUTHOR — never add AI-assistant attribution to commits](#no-coauthor)
- [§ATLAS-IS-INDEX — update ATLAS.md when structure changes](#atlas-is-index)
- [§MAINTAIN-DOCS — append substantive Q&A to docs/FAQ.md](#maintain-docs)
- [§SMOKE-AFTER-CHANGE — run the smoke set after touching runtime](#smoke-after-change)
- [§ADR-BEFORE-MAJOR — non-trivial decisions get an ADR before shipping](#adr-before-major)

**Operations / deploy** *(add as scars accumulate)*
- _(e.g. §ROLLBACK-WINDOW — every release must be reversible within N minutes)_

**Security / secrets**
- _(e.g. §NO-PII-IN-LOGS, §SECRET-ROTATION-90D)_

**Performance / hot paths**
- _(e.g. §N+1-GUARDRAIL, §CACHE-INVALIDATION-RULE)_

**Data integrity / migrations**
- _(e.g. §MIGRATIONS-IDEMPOTENT, §NO-DOWNTIME-COLUMN-ADD)_

**Domain-specific** *(add `## <Domain>` headings as you accumulate scars)*

---

## Process / hygiene

<a id="no-coauthor"></a>
### §NO-COAUTHOR — never add AI-assistant attribution to commits

Project preference. Do not add `Co-Authored-By: Claude …` or equivalent lines
in commits.

---

<a id="atlas-is-index"></a>
### §ATLAS-IS-INDEX — update ATLAS.md when structure changes

If you add a top-level module, a new message type, a new external dependency,
or move files across sections — **update [`ATLAS.md`](ATLAS.md) in the same
commit**. ATLAS is the graph entry point; a stale ATLAS forces every future
agent to grep. Use `atlas check` to verify the file still parses.

---

<a id="maintain-docs"></a>
### §MAINTAIN-DOCS — append substantive Q&A to docs/FAQ.md

When a user asks a substantive inner-workings question and you answer it well,
append the Q&A to `docs/FAQ.md`. Future agents reading the FAQ then know
without re-asking.

---

<a id="smoke-after-change"></a>
### §SMOKE-AFTER-CHANGE — run the smoke set after touching runtime

The smoke command lives in ATLAS §5. Run it after any change to the runtime or
shared modules. **Don't ship commits that don't green the smoke set.**

---

<a id="adr-before-major"></a>
### §ADR-BEFORE-MAJOR — non-trivial decisions get an ADR before shipping

If a change introduces a new external dep, alters a public contract, or changes
a long-standing convention — write an ADR in `docs/adr/NNNN-short-name.md` (copy
`docs/adr/0000-template.md`) and link it from ATLAS §A3 **before** the
implementation lands. ADRs are immutable once accepted; supersede by writing a
new one that references the old.

---

## Adding scars

When this project earns a new lesson, scaffold a stub with
`atlas anchor add NAME "summary"`, then fill in Symptom / Root cause / Do NOT /
Do / Where / Shipped-in and cite the anchor in the commit that fixes it. Per
entry:

    <a id="anchor-name"></a>
    ### §ANCHOR-NAME — one-line summary
    **Symptom.** What the user/agent observes.
    **Root cause.** Why it happens.
    **Do NOT.** Anti-patterns to avoid.
    **Do.** Correct pattern with code or steps.
    **Where.** path/to/file.ext::function_name
    **Shipped in.** <commit sha>.