why - SKILL.md Agent Skill

name: why description: "sr:why — Search explanation records written by specrails agents during the OpenSpec implementation pipeline." license: MIT compatibility: "Requires git." metadata: author: specrails version: "1.0"

/specrails:why — In-Context Help

Searches explanation records written by sr-architect, sr-developer, and sr-reviewer agents during the OpenSpec implementation pipeline.

Records are stored in .claude/agent-memory/explanations/ as Markdown files with YAML frontmatter (agent, feature, tags, date).

Usage:

/specrails:why — list the 20 most recent explanation records
/specrails:why <query> — search records by keyword or tag

Step 1: Find explanation records

Glob all files matching .claude/agent-memory/explanations/*.md.

If the directory does not exist or contains no files: Print:

No explanation records found yet.

Explanation records are written by the sr-architect, sr-developer, and sr-reviewer agents
when they make significant decisions during feature implementation.

Run `/specrails:implement` on a feature to generate your first explanation records.

Then stop.

Step 2: Handle no-argument mode (listing)

If $ARGUMENTS is empty:

Read each explanation record file. Extract from frontmatter: date, agent, feature, tags. Extract the first sentence of the ## Decision section as the decision summary.

Sort records by date descending. Print the 20 most recent as a Markdown table:

## Recent Explanation Records

| Date | Agent | Feature | Tags | Decision |
|------|-------|---------|------|----------|
| 2026-03-14 | sr-architect | in-context-help | [templates, commands] | Chose flat directory over per-agent subdirectories. |
| ...  | ...   | ...     | ...  | ...      |

Then stop.

Step 3: Handle query mode (search)

If $ARGUMENTS is non-empty, treat the full string as the search query.

For each explanation record file:

Read the full file content
Score the record against the query:
- Filename contains a query word: +3 points per matching word
- Frontmatter tags array contains an exact query word: +3 points per matching tag
- Frontmatter feature contains a query word: +2 points
- Body text contains a query word: +1 point per occurrence (case-insensitive)
Sum the score

Sort records by score descending. Take the top 5 records with score > 0.

If no records score > 0: Print:

No explanation records match "<query>".

Then list all unique tags from existing records:

## Available Tags

[sorted list of all unique tags from all explanation records]

Try `/specrails:why <tag>` with one of the tags above, or `/specrails:why` to browse all records.

If records match, print each matching record in full, separated by ---:

## Results for "<query>" (N matches)

---

**[date] [agent] — [feature]**
Tags: [tag1, tag2]

[full record body]

---

**[date] [agent] — [feature]**
...