wherefore AGENTS.md

wherefore: agent instructions

This repo uses a wherefore/ directory: a plain-markdown record of technical decisions (what was chosen, why, what was rejected) and open questions. Any agent can read and maintain it by following the rules below. Do not invent a second location; if wherefore/ exists, use it.

Directory layout

wherefore/
  topics.md         controlled tag vocabulary: Areas and Topics
  log/YYYY-MM-DD-short-slug.md    one decision per file
  questions/Q-NNN-short-slug.md   one question per file (ID prefix + scannable slug)
  plan/P-NNN-short-slug.md        forward-looking plan items, one per file

If wherefore/ does not exist, create it plus log/, questions/, a starter topics.md, and a README.md containing exactly:

# wherefore

A decision log in plain markdown. Each file captures what was decided, why, and what was ruled out.

Maintained by the [wherefore](https://github.com/DustinVK/wherefore) skill.

Reading (answering "why did we...", "what did we decide about...")

1. Read only the leading frontmatter block of every log/*.md file (it is short), and shortlist by area, topic, story, or title. Then open only the shortlisted files (1-5), not the whole log. The frontmatter also carries each entry's status and superseded_by, so filtering and chain-following need nothing else.
2. Treat status active, current, or absent as current. For a superseded entry, follow its superseded_by slug to the replacement (repeat until you reach an active entry). Exclude obsolete entries unless asked about history.
3. Answer from active entries, lead with the current decision, cite the source by date + title + filename. If nothing matches, say so plainly. Never fabricate.
4. After answering, read the questions/Q-*.md frontmatter and surface briefly any open questions whose areas overlap.

Writing a decision (capture)

Distill the discussion to its useful residue; do not transcribe. Write wherefore/log/YYYY-MM-DD-short-slug.md (slug: short, lowercase, hyphenated) with this EXACT frontmatter and section structure: