---
name: refresh-docs
description: Regenerate the docs dashboard at paths.index. Walks active/ briefs, specs, and plans plus the decisions folder, reads frontmatter, writes In Progress / Recently Archived / ADRs sections. Last 10 archived entries, archival date preferred, updated as fallback.
---

## Inputs

None. The skill operates on what it finds on disk, scoped by
`paths:` in `.ai-local/project.yaml`.

## Personas

None. Mechanical.

## Rules loaded

From `.ai-local/project.yaml`: `paths.*`. No rule interpretation. If
`project.yaml` is missing or malformed, stop and ask.

## Steps

1. **Orient.** Read `.ai-local/project.yaml`. Resolve `paths.briefs`,
   `paths.specs`, `paths.plans`, `paths.decisions`,
   `paths.index`.

2. **Collect active entries.** For each of
   `<paths.briefs>/active/`, `<paths.specs>/active/`,
   `<paths.plans>/active/`, read every `*.md` file's
   frontmatter. Record `id`, `type`, `status`, `owner`,
   `updated`, and for plans `progress.done` / `progress.total`.

3. **Collect archived entries.** For each of the three
   `archive/` directories, read frontmatter. Rank entries by
   archival date (file mtime at the `archive/` path) when
   available, falling back to `updated` from frontmatter. Keep
   the most recent 10 across all three types combined.

4. **Collect ADRs.** Read every `*.md` in
   `<paths.decisions>/`. Record `id`, title (first H1), and
   `status`. Sort by `id` ascending.

5. **Write the dashboard.** Overwrite `<paths.index>` with this
   structure:

   ```markdown
   # Documentation

   _Last updated by agent: YYYY-MM-DD_

   This dashboard is regenerated by `/refresh-docs`. Do
   not edit by hand — your changes will be overwritten.

   ## In Progress

   | ID  | Type | Status | Progress | Owner | Updated |
   | --- | ---- | ------ | -------- | ----- | ------- |
   | …   | …    | …      | …        | …     | …       |

   ## Recently Archived

   - YYYY-MM-DD — <id> (<type>, done)

   ## Decisions (ADRs)

   - NNNN — <title> (<status>)
   ```

   Empty sections render as `_None._` rather than being
   omitted. The `Progress` column for non-plan rows is blank.

6. **Write no other file.** The skill mutates exactly
   `<paths.index>`.

## Outputs

- `<paths.index>` rewritten in place.