ask

Wherefore: ask

Answer a question by finding the relevant past discussions and summarizing what they actually say. The cardinal rule: ground every answer in entries that exist. If the wherefore has nothing on the topic, say so: a confident answer assembled from nothing is worse than "I didn't find anything about that."

No em dashes. Periods, commas, colons, semicolons, or parentheses instead. Firm project rule.

Never delete anything under a wherefore/ data dir. Retire, do not delete.

Storage layout

The wherefore lives under a repo-relative wherefore/ directory:

wherefore/
├── topics.md                     # controlled topic vocabulary
├── questions/
│   └── Q-NNN-short-slug.md       # one file per question (ID prefix + scannable slug)
└── log/
    └── YYYY-MM-DD-short-slug.md  # one file per discussion

The frontmatter of the entry and question files is the single source of truth; you derive what you need at read time. If wherefore/ or wherefore/log/ does not exist, or log/ holds no *.md entries, tell the user the wherefore is empty or not set up yet; do not fabricate an answer.

Workflow

1. Parse the question onto the right facet. Decide whether it's about a feature slice (an area: "the price calculator", "international shipping", "the order process") or a cross-cutting concern (a topic: auth, postgres, performance), or both. Most "why did we build X this way" questions name a feature, so map those onto areas first. Also pull any ticket/story IDs and key nouns. Glance at topics.md (which lists both Areas and Topics) to map the user's wording onto the canonical tags: they may say "checkout" when the area is order-process, or "login" when the topic is auth.

2. Shortlist from entry frontmatter. Read only the leading frontmatter block of every log entry in one cheap pass, then pick the files worth opening. Do not open every entry file. One command that dumps just the frontmatter (each block is ~10 lines, far cheaper than the full bodies):

   for f in wherefore/log/*.md; do
     awk -v F="$f" 'BEGIN{print "=== " F " ==="}
       /^---[[:space:]]*$/ { n++; if (n==2) exit; next }
       n==1 { print }' "$f"
   done
   

   From that dump, select entries whose areas, topics, stories, or title plausibly match (typically 1-5). The dump also carries each entry's status and superseded_by, so you can filter and follow supersession chains without a second pass.

   • Prefer entries whose status is active, current, or absent (all treated as active). Include superseded entries only when no active entry covers the topic, so you can follow the chain to the current answer. Exclude obsolete entries entirely unless the user explicitly asks about historical decisions.
   • If the frontmatter fields look too sparse to shortlist on (older entries with thin tags), widen the same dump to grep the bodies for your key nouns.