# Update Docs

> Update all project documentation to reflect the current state of the codebase. Use after finishing a feature, refactor, or any meaningful change — or whenever docs feel stale.

- Skill: `rubenglez/update-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rubenglez/update-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rubenglez/update-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: rubenglez (https://skillmd.com/u/rubenglez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rubenglez/update-docs

---


# Update Docs

## Step 1: Build a current-state summary

Before writing anything, read everything.

**Git history**: `git log --oneline -20`, note which areas were touched.

**Existing docs**: read all files under `.harness/` and any root docs (README.md, DESIGN.md, CHANGELOG.md).

**Codebase**: scan key directories, check package manifests, note what's implemented, removed, or changed. Verify the project sync standard: `CLAUDE.md` should contain only `@AGENTS.md`, and `AGENTS.md` should contain only durable, agent-facing facts that are not reliably inferable from the repo itself.

**Reconcile phase status.** This skill is the owner of status consistency — no other skill cross-checks it. Phase state lives in three sources that drift independently: per-feature `Status:` lines in `.harness/engineering/features/`, phase markers in `.harness/product/roadmap.md`, and the latest `.harness/qa/report.md`. Compare them against each other and against the actual code:
- A feature marked `done` whose code isn't there (or vice versa) → fix the spec to match reality.
- A roadmap phase whose features are all `done` but is still marked planned → advance the roadmap marker.
- A `qa/report.md` listing outstanding failures for a feature still marked `done` → the spec is lying; reflect the failure.
Record each disagreement in the summary's "Stale docs" section so Subagent A corrects it.

Synthesize a **current-state summary** (subagents receive this verbatim):

```
## What the product is now
[One paragraph: what it does, who it's for, current state]

## Recent changes not yet in docs
- [change] — [which docs this affects]

## Stale docs
- [file path] — [what's outdated and why]

## Accurate docs (do not touch)
- [file path] — [why it's still current]

## Missing docs
- [file path that should exist but doesn't, and why]
```

## Step 2: Spawn two subagents in parallel

> **Runtime note:** subagents are Claude-specific. Without them (e.g. Codex), see [../_shared/runtime-parallelism.md](../_shared/runtime-parallelism.md) and write the two doc sets sequentially — you remain the single writer either way.

Pass the full current-state summary to each — they cannot read the conversation or codebase themselves.

Subagents A and B write different files — two subagents must never edit the same `.harness/` file (one writer per doc — concurrent edits merge byte-wise but conflict semantically).

**Subagent A** updates internal docs under `.harness/`: `product.md`, `roadmap.md`, `competitors.md`, `ux.md`, `CONTEXT.md`, `architecture.md`, `implementation-plan.md`, `adr/`, `features/[slug].md`, `qa/report.md`.

Only update a file if the summary shows it's stale. Do not touch accurate files. Never link to `.harness/` from public docs.

**Subagent B** updates public docs: `README.md`, `DESIGN.md`, `CHANGELOG.md`, `AGENTS.md`.

Keep public docs strictly separated from internal content — no `.harness/` links, no internal strategy, no implementation details.

See [REFERENCE.md](REFERENCE.md) for the detailed rules and content guidelines for each file.

## Step 3: Refresh the doc index and commit

After both subagents finish, run `doctier agents --write` to refresh the managed doc index in AGENTS.md (the block between `<!-- doctier:begin -->` and `<!-- doctier:end -->`). Then commit everything — worktrees and future sessions only see committed `.harness/` content:

```bash
for f in .harness AGENTS.md README.md DESIGN.md CHANGELOG.md CLAUDE.md; do
  [ -e "$f" ] && git add "$f"
done
git commit -m "docs: sync with current state"
```

## Step 4: Confirm

Report:
- Every file updated, with one line on what changed
- Every file left untouched and why
- Confirmation that the doc index refresh and the commit landed
- Any doc gaps this run couldn't fill

Recommend next step: release the phase with /ship if it's user-ready, or start the next phase with /implement.