prime

What this skill does

# Prime Architecture Context

Load existing ADRs and specs into the session so Claude can give architecture-aware responses.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the ADR and spec directories. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module; otherwise, in a workspace, aggregate across all modules. The resolved ADR directory is `{adr-dir}` and spec directory is `{spec-dir}`.

   <!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Cross-Module Aggregation" -->

   **Cross-module aggregation**: When in aggregate mode (no `--module`, workspace detected), iterate over all discovered modules. For each module, resolve its artifact paths independently. Prefix every artifact reference in the output with the module name in square brackets: `[api] ADR-0001`, `[worker] SPEC-0003`. When `--module` is provided, scope to that single module — no prefix needed. When in single-module mode (no workspace), operate normally without prefixes.

1. **Check if init has been run**: Read `CLAUDE.md` at the project root (or module root if `--module` is set) and check if it contains references to an ADR or spec directory. If CLAUDE.md does not exist or lacks SDD plugin references, output:

   ```
   CLAUDE.md does not have SDD plugin references. Run `/sdd:init` first to set up your project, then re-run `/sdd:prime`.
   ```

   Then stop. Do NOT proceed with scanning.

1a. **Tier 2 session-start update** (v5.0.0+):

   <!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 2 Session-Start Update via /sdd:prime" -->

   Run `qmd update` (cheap file-mtime scan) on entry to catch changes from outside the current Claude session — other developers, CI bots, branch switches, manually edited files. Skip the update when the qmd index was touched within the last 60 seconds (back-to-back primes are common; the short-circuit prevents redundant work).

   1. Run `qmd status --json` and parse the response to find the maximum `lastUpdated` timestamp across this-repo collections (identified via the exact-prefix match algorithm from the collection names — e.g., `claude-plugin-sdd-adrs`, `claude-plugin-sdd-specs`).
   2. If the most recent timestamp is within the last 60 seconds, skip the update entirely (no output).
   3. Otherwise, invoke `qmd update`. The update is silent on success when the diff is empty. If the update added/modified/removed any documents, print exactly one line in the report header (between the `## Architecture Context Loaded` heading and the section tables): `Refreshed index ({a} added, {m} updated, {r} removed across this repo's collections)`.
   4. After the update, run `qmd status --json` again and sum the `(documents - embedded)` count across this repo's collections. If non-zero, surface a one-line note in the report header (after the refresh line, if any): `{N} chunks unembedded — run \`/sdd:index embed\` (≈{seconds}s on this machine, foreground; or wait for the next mutation skill to backfill)`. Do NOT prompt via AskUserQuestion — the surface is informational, not a decision the user needs to make right now.

2. **Retrieve artifacts via qmd** (unified path for all modes, v5.1.0+):
   
   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-Smart Context Loading" -->
   
   All artifact retrieval now uses qmd hybrid search for consistency, flexibility, and efficiency. Both untargeted and topic-filtered modes use the same code path with different parameters, executed via the `qmd query` CLI.
   
   **For untargeted priming** (`/sdd:prime` with no topic):
   - Query for all ADRs with `qmd query --json -c {repo}-adrs --limit 10000 --minScore 0` plus a second query for all specs with `qmd query --json -c {repo}-specs --limit 10000 --minScore 0`
   - In workspace mode, repeat for each module's per-module collections (`{repo}-{module}-adrs`, etc.)
   - The `--limit 10000` and `--minScore 0` retrieve all matches without filtering
   
   **For topic-filtered priming** (`/sdd:prime {topic}`):
   - Construct a hybrid query with both `lex` (keyword match) and `vec` (semantic match) sub-queries per `references/qmd-helpers.md` § "Hybrid Retrieval"
   - Run: `qmd query --json -c {repo}-adrs -c {repo}-specs --limit 8 --minScore 0.3 '<queries>'`
   - If zero candidates above `minScore: 0.3`, output: `No ADRs or specs matched the topic "{topic}". Try a broader term, or run `/sdd:prime` without a topic to see all artifacts.`
   
   For each retrieved artifact:
   - Parse the JSON response to extract: ID, title (from first `#` heading), status, superseded-by (from frontmatter)
   - For ADRs: extract summary from first 2-3 sentences of `## Decision Outcome`
   - For specs: extract summary from first sentence of `## Overview`; count requirements and scenarios
   - Sort by artifact ID number (natural sort: ADR-0001, ADR-0002, ..., SPEC-0001, ...)

3. **Filter non-authoritative artifacts** (applies to untargeted mode; topic-filtered mode surfaces all matches with badges):
   - Partition into authoritative (`accepted`, `proposed`, `draft`, `review`, `approved`, `implemented`, or missing) and non-authoritative (`superseded`, `deprecated`, `rejected`)
   - Exclude non-authoritative from main tables, collect for footer
   - In topic-filtered mode, surface non-authoritative matches with a `⚠` badge since topic filtering is often investigative

3a. **Status Field Extraction algorithm**. Two formats are supported because legacy SDD-using repos predate YAML frontmatter:

   1. **YAML frontmatter** (canonical, current SDD template): look for a `status:` key inside the `---` … `---` frontmatter block at the top of the file.
   2. **Inline bullet** (legacy / hand-authored): if no YAML frontmatter exists OR YAML has no `status:` field, scan the first 30 lines for a line matching `- **Status:** {value}` (case-insensitive on "Status"; tolerate `*` or `+` as the bullet marker; tolerate `Status:` without the bold).
   3. **Strip refinement notes**: the inline-bullet form sometimes carries a parenthetical refinement note: `- **Status:** accepted (refined by ADR-0010, 2026-05-03)`. Split on the first `(`, trim trailing whitespace, and use only the leading word ("accepted"). The parenthetical content is preserved in the source file but is not rendered in prime tables — it would blow out column width for a corner case better surfaced by `/sdd:graph` or by reading the artifact directly.
   4. **No status found**: if neither form yields a value, record the artifact as having no parseable status. Render as `—` in the table when other artifacts in the same corpus have status; drop the Status column entirely when *zero* artifacts in the corpus have status (see Step 5 rendering rule).

4. **Extract summaries for context** (v5.1.0+):
   
   To make prime output immediately useful without opening files, extract concise summaries:
   - **For ADRs**: first 2-3 sentences from the decision outcome explaining what was decided and why
   - **For specs**: first sentence of the Overview section, truncated at ~140 characters
   - These summaries appear alongside titles in all output modes to provide at-a-glance context

5. **Handle edge cases**:
   - If `{adr-dir}` does not exist: "The `{adr-dir}` directory does not exist. Run `/sdd:adr [description]` to create your first ADR."
   - If `{spec-dir}` does not exist: "The `{spec-dir}` directory does not exist. Run `/sdd:spec [capability]` to create your first spec."
   - If neither directory has any artifacts: "No design artifacts found. Create an ADR with `/sdd:adr` or a spec with `/sdd:spec` first."
   - If ADRs exist but no specs (or vice versa), present whichever exists and note the other is empty

7. **Present results** using the appropriate output format below.

## Output

### Without topic filter (`/sdd:prime`