Capture

Wherefore: capture

Turn a raw or AI-generated discussion into one compact, retrievable wherefore entry. Preserve the useful residue (what was decided, why, and what was rejected), not a transcript. Months later, someone asking "why did we build it this way?" should get the answer in a few sentences.

Writing style

The record must read well as a raw markdown file, not just in the dashboard. Editors and the GitHub blob view are where most people read it.

• No em dashes anywhere. Use periods, commas, colons, semicolons, or parentheses. Firm project rule.
• Decisions are verdict-led. Open each bullet with the ruling as a short standalone clause; put elaboration after it or in Why. Someone reading only the first clause of every bullet should still get the full outcome.
• One decision per bullet. Split compound bullets.
• Do not use inline bold to fake structure. The lead clause carries the scan. Bold scattered mid-sentence is the main cause of wall-of-text records. Reserve emphasis for a rare load-bearing term.
• Keep sentences short and concrete.
• Why is the single home for rationale. State the outcome in Decisions, the reasoning in Why. Do not scatter reasoning across decision bullets.
• Unresolved threads are not decisions. They go to Open questions and become a Q-NNN, never a Decisions bullet dressed as certainty.

Verdict-led, in practice:

• Weak: "There are two fulfillment paths, direct and via inventory, and after weighing platform fit we lean toward starting inventory-based and moving to direct later."
• Strong: "Start inventory-based, move to direct later. Two paths exist: direct (seller ships to buyer) and via inventory (trader stocks, then ships)."

Storage layout

All entries live under a repo-relative wherefore/ directory:

wherefore/
├── README.md          # what this directory is + link to the plugin
├── topics.md          # controlled tag vocabulary (areas + topics)
├── 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

There is no separate index file. The frontmatter in the entry and question files is the single source of truth; readers derive what they need at read time. Do not create, append to, or maintain any index file. A repo that still carries a legacy index file from an older plugin version is no longer using it; leave it untouched (or mention it can be deleted), never recreate it.

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) Claude Code skill.

Never invent a second wherefore location. If the repo already has wherefore/, use it.

Entry format

Write every entry with this exact structure:

---
date: YYYY-MM-DD
title: "Short human-readable title, `.
    - Old entry frontmatter: `status: superseded`, `superseded_by: `, `superseded_date: YYYY-MM-DD`.
    - Old entry first body line (after frontmatter, before `## Summary`): `SUPERSEDED YYYY-MM-DD -> see . Kept for history, not current.`

8. Write `wherefore/log/YYYY-MM-DD-short-slug.md`. Slug short, lowercase, hyphenated, recognizable (`oauth-token-refresh`, not `discussion-about-the-auth-stuff`). If the name exists, add a short suffix; never overwrite.

9. Register open questions. For each genuine unresolved item:
    - Next Q-ID = (highest `id:` across `wherefore/questions/Q-*.md`) + 1. Derive it from the files, e.g. `ls wherefore/questions/Q-*.md 2>/dev/null | sed -E 's|.*/Q-0*([0-9]+).*|\1|' | sort -n | tail -1`. If the directory is empty or absent, start at Q-001. IDs are sequential and never reused. (The regex tolerates both the legacy `Q-NNN.md` and the current `Q-NNN-slug.md` naming.)
    - Prefix the entry's item with the ID: `- Q-001: How should we ...`
    - Create `wherefore/questions/Q-NNN-short-slug.md`, leaving `resolution` and `resolution_slug` blank. Name it like a log entry: `Q-` + the zero-padded ID + a short, lowercase, hyphenated slug distilled from the question (`Q-001-eu-buyer-tax`, not `Q-001-question-about-tax-stuff`). The `Q-NNN` prefix keeps questions sorted and greppable by number; the slug is for human scanning; the authoritative ID is always the `id:` frontmatter field.
      ```
      ---
      id: Q-001
      question: "How should we handle tax for EU buyers?"
      status: open
      areas: [international-shipping, price-calculator]
      asked_date: YYYY-MM-DD
      asked_slug: 2026-06-23-rls-tenant-isolation
      resolution:
      resolution_slug:
      ---
      ```
      Report the assigned Q-IDs.

10. Resolve questions this discussion answers. If open Q files exist:
    - Shortlist by area/topic overlap, or where the source explicitly addresses the question.
    - Ask the user which are now resolved; do not auto-close.
    - For each confirmed: set the Q file `status: resolved`, fill `resolution` (one quoted sentence), set `resolution_slug` to the new slug. Report closures.
    - No match: skip silently.

11. Report back. Show the title, assigned areas and topics (flag any new tag), linked stories, any supersession applied, and any Q-IDs assigned or closed. This is the approval moment: you distilled and tagged on the user's behalf, so let them correct it before it ossifies. There is no index to update; `ask` derives everything from the frontmatter you just wrote.

## Examples

Reversal. Input: "We're dropping RLS and going schema-per-tenant after the perf testing." Before writing, dump entry frontmatter and scan for active entries sharing `multi-tenancy` or `postgres`, surface the RLS entry, and confirm the reversal. On confirmation, write the new entry with `supersedes: 2026-06-23-rls-tenant-isolation`, mutate the old entry's frontmatter (`status: superseded`, `superseded_by`, `superseded_date`) and add its banner line, and report every file touched.

No decision. Input: a long thread weighing GraphQL caching with no conclusion. The Decisions section reads "No decision, see Open questions"; the contenders go under Open questions, each becoming a `Q-NNN-short-slug.md` so a later discussion can close them out explicitly.

Two threads in one discussion. Input: a thread covering both an order PDF renderer swap and a separate cart price-suggestion feature, which share no causal link. Write two files (`2026-06-24-order-pdf-renderer.md`, `2026-06-24-buyer-price-suggestion.md`), each with its own tags. Report: "Split into 2 entries; the two decisions are unrelated and would be retrieved separately."

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DustinVK](https://github.com/DustinVK)
- **Source:** [DustinVK/wherefore](https://github.com/DustinVK/wherefore)
- **License:** MIT

Install and usage instructions live in the source repository linked above.