keeping-docs-alive

Keeping docs alive during execution

Living docs are the nervous system between sessions. Without them kept up to date, the next session (human or AI) starts from scratch or worse — starts off wrong.

When this skill activates

Auto-activates when the context involves:

• "Finished task X" / "task X is done"
• "I'm going to pause" / "stopping for today" / "we'll continue tomorrow"
• "Phase X complete"
• "I decided to change the approach to Y"
• "I'm going to open a PR / final commit"
• A plan checkbox being marked as complete

Procedure (3 mandatory steps)

Step 1 — Update the active plan

If the current work corresponds to a task in the plan at docs/superpowers/specs/<plan>.md:

1. Check the checkboxes of the completed steps: [ ] → [x].
2. Add a note if the task deviated from the plan (e.g., "I had to add X because Y").
3. Update the count if there's a "completed: N/M" field in the plan.

Step 2 — Update CLAUDE.md

Section 4 (Feature layer) — if there was a phase/feature change:

• **Fase ativa:** should point to the actual phase in progress.
• **Feature-âncora:** likewise.

Section 5 (Session layer) — whenever you pause/resume:

• Point to the current session file: .claude/sessions/<data>-fase-N-<descrição>.md.

Section 9 (Next steps) — update to reflect what comes next.

Step 3 — Create/update the session file

.claude/sessions/<YYYY-MM-DD>-fase-<N>-<descrição>.md:

# Sessão · YYYY-MM-DD · Fase N — <Descrição>

## Estado ao pausar

- **Plano ativo:** `docs/superpowers/specs/<file>.md`
- **Última task completada:** Task N (Step N.M)
- **Próxima ação ao retomar:** <1 frase específica>

## O que foi feito nesta sessão

- ...

## Pegadinhas descobertas

- (se houver)

## Decisões emergentes

- (se houver — pode virar ADR)

## Comandos engatilhados

\`\`\`bash
# Pra retomar:
cd <pasta>
docker compose ...
\`\`\`

When NOT to activate

• ❌ Trivial change (typo, comment) — not worth cluttering the docs.
• ❌ Mid-task ("I just wrote a function") — wait until the whole task is complete.
• ❌ Refactoring that doesn't change the phase/feature/scope.

Good example

User: "Finished Task 4. I'm going to pause for today."

Skill activates: "I'll update 3 things:

1. docs/superpowers/specs/2026-05-27-fase-0-spike.md — mark steps 4.1 through 4.11 as [x].
2. CLAUDE.md section 5 — point to .claude/sessions/2026-05-27-fase-0-task5.md.
3. Create .claude/sessions/2026-05-27-fase-0-task5.md with 'Last task completed: Task 4 · Next action: implement the Task 5 component'."

Anti-patterns

• ❌ Updating only the checkboxes and forgetting CLAUDE.md.
• ❌ Creating a session with "did several things" and no actionable detail.
• ❌ Not updating when "I'll continue tomorrow" — tomorrow you'll forget.