---
description: Redraft all Tier 2 wiki files (wiki/features/*.md) by re-deriving prose from current code, tests, and ADRs. Output to .wiki-draft/ for human review.
---

# /redraft-tier2

Refresh Tier 2 wiki content by re-deriving each file from current repo state. Output goes to `.wiki-draft/` only — never directly to `wiki/`. Human reviews via PR.

Per [ADR-0015](../wiki/decisions/0015-tier2-llm-as-host-agent.md): you are the LLM. No external API gets called.

## What counts as Tier 2

Today, only `wiki/features/*.md` (excluding `_index.md` and `_template.md`). The authoritative classifier is `koala_wiki::tier::tier_of` in `crates/koala-wiki/src/tier.rs`.

```
ls wiki/features/*.md | grep -vE '/_(index|template)\.md$'
```

## Steps

1. **Enumerate Tier 2 files** with the command above.

2. **For each Tier 2 file `<F>`:**
   - Read `<F>` to learn its frontmatter, structure, and which ADRs it references.
   - Read those ADRs (frontmatter `decisions:` field or inline `[ADR-NNNN](...)` links).
   - Read the implementing crate. Mapping: `wiki/features/<feature>.md` → `crates/koala-<feature>/src/` (e.g. `drift-detector.md` → `crates/koala-drift/`). For features that span multiple crates, follow the references in the existing prose.
   - Rewrite **only the prose body**. Preserve verbatim:
     - The frontmatter block (`---...---`)
     - Acceptance criteria checkboxes (`- [x]` / `- [ ]` lines — `feature_acceptance` drift check verifies these)
     - File path / basename
   - Write the rewritten content to `.wiki-draft/features/<basename>.md`. Use the `Write` tool directly (the `.wiki-draft/` dir is a normal mirror of `wiki/`).

3. **Open review PRs:**

   ```bash
   koala-core wiki refresh-pr            # one PR per draft: branch → cp → commit → push → gh pr create
   koala-core wiki refresh-pr --dry-run  # preview the plan without touching git or gh
   ```

   The command does the full pipeline for each draft: branches off `main`, copies the draft into `wiki/`, commits, pushes, runs `gh pr create --label wiki-refresh`, then returns to `main` and removes the consumed draft. **Pre-flight requires you to be on `main` with a clean working tree** (untracked `.wiki-draft/` files are tolerated since they're the input).

   If `gh pr create` fails (e.g., org blocks Actions write), the branch was already pushed — the URL pattern is printed in the result line; open the PR manually.

4. **Record reviewer artifact** (Rule 11 — required by `koala.artifact-required` gate):

   ```bash
   koala-core artifact record evaluator \
     --name tier2-redraft-<YYYY-Q> \
     --round <next> \
     --reviewer agent:claude-code \
     -- bash -c "ls .wiki-draft/features/ 2>/dev/null | wc -l"
   ```

   `<next>` = highest existing `.review/round-N/` + 1.

## Constraints

- **Never** edit `wiki/features/*.md` outside this redraft pipeline (always go through `.wiki-draft/` first, then cp into `wiki/` as part of step 3's PR commit). Direct edits bypass the audit trail.
- **Never** edit Tier 1 (`_index.md`, `_tags/*`, `health.md`) — they're auto-generated.
- **Never** edit Tier 3 (ADRs, vision.md, roadmap.md, runbook.md, README.md, tech-debt.md, post-mortems, specs, rfcs, migrations) — humans only.
- **Never** flip acceptance checkboxes. If you believe an unchecked box is now satisfied, surface it in the PR description; the human checks it.

## When to run

- Quarterly (`.github/workflows/quarterly-cron.yml` opens a "time to redraft Tier 2" issue as a reminder)
- After major architecture refactor that invalidates feature prose
- After ADR supersede that touches Tier 2 content

## Verification

After running, confirm via:

```bash
cargo run -q -p koala-cli -- check --profile strict --sample 100
```

The check will refuse if any draft accidentally landed outside `.wiki-draft/`, or if a feature file's acceptance refs broke.
