Refresh

---
name: refresh
description: >
  Detect drift in .arkhe/roadmap/ context files and regenerate them from the current
  codebase state. Scaffolds context directory if missing. Use when user runs
  /roadmap:refresh, mentions "refresh context", "update context", "init roadmap",
  "stale context", or "scaffold roadmap".
disable-model-invocation: true
argument-hint: "[init | check | all | project | architecture | documents]"
allowed-tools: Read, Glob, Grep, Write, Bash
---

# Context Directory Refresh

Detect drift in `.arkhe/roadmap/` context files and regenerate them using a hybrid format (condensed summary + references to authoritative docs).

## Arguments

Parse from `$ARGUMENTS`:

| Mode | Description |
|------|-------------|
| `init` | Scaffold `.arkhe/roadmap/` with all 3 files from scratch |
| `check` | Detect drift only — report staleness, don't write |
| `all` | Regenerate all 3 context files |
| `project` | Regenerate only project.md |
| `architecture` | Regenerate only architecture.md |
| `documents` | Regenerate only documents.md |
| _(none)_ | Run `check`, then ask which files to refresh |

## Step 1: Run Drift Detection

Run the detection script:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/refresh/scripts/detect_context_drift.py .
```

Parse the JSON output. Present a drift report table:

```
## Context Directory Status

| File | Exists | Staleness | Days | Commits Since | feat/fix |
|------|--------|-----------|------|---------------|----------|
| project.md | Yes/No | fresh/aging/stale/very_stale | N | N | N |
| architecture.md | Yes/No | ... | ... | ... | ... |
| documents.md | Yes/No | ... | ... | ... | ... |

New modules not in architecture.md: {list or "none"}
```

**For `check` mode**: Stop here. Present the report and suggest which files need attention.

## Step 2: Context Discovery

For `init`, `all`, or single-file modes, run the shared context discovery protocol from [CONTEXT_DISCOVERY.md](../../references/CONTEXT_DISCOVERY.md). Gather:

- From `README.md`: project purpose, target users
- From `CLAUDE.md`: constraints, conventions, tech stack
- From build files: tech stack detection via [TECH_STACK_DETECTION.md](../../references/TECH_STACK_DETECTION.md)
- From `docs/**/*.md`: documentation inventory
- From module globs: module inventory with file counts
- From `docs/adr/**/*.md`: ADR titles and status
- From `arkhe/specs/*/spec.md`: spec pipeline

## Step 3: Generate Files

Generate each requested file using the hybrid format below. See [WORKFLOW.md](WORKFLOW.md) for detailed generation protocol per file.

### Hybrid Format Template

```markdown
# {Title}
_Auto-generated by /roadmap:refresh on {date}. Edit freely — regenerate with `/roadmap:refresh {file}`._

## Summary
{3-5 bullet points, <300 tokens — the essential facts}

## Details
{Structured data: tables, lists}

## References
{Pointers to authoritative docs}
- `{doc_path}` — {one-line description}
```

### Generation Sources

| File | Primary Sources |
|------|----------------|
| `project.md` | README.md, CLAUDE.md, gap analyses, existing project.md |
| `architecture.md` | Build files, module globs, ADRs, CLAUDE.md architecture section |
| `documents.md` | Phase 5 doc scan results, spec files, gap analyses, ADRs |

## Step 4: Confirm and Write

Before writing each file:

1. Show current content (if exists) or "Does not exist"
2. Show proposed new content
3. Ask: **"Write this to `{context_dir}/{filename}`?"**

Create the `.arkhe/roadmap/` directory if it doesn't exist.

Never overwrite without confirmation.

## References

- [WORKFLOW.md](WORKFLOW.md) — Detailed generation protocol per file
- [EXAMPLES.md](EXAMPLES.md) — Usage examples
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — Common issues