document-plan

---
name: document-plan
description: Create a baby-step documentation plan (overview + domain deep dives for RAG). Asks doc language before writing. Use when planning repo docs or invoking /document-plan.
---

## STOP - Read before ANY tool call

1. Read `{{GUARDRAILS_PATH}}`
2. Read `_shared/sdd-artifacts/SESSION.md`; load session-state for `$Cwd`
3. If the relevant gate is not approved: **STOP** - ask user **(pt-BR)** - do **NOT** Write/Shell
4. SDD/develop skills: after **ONE** step/task, **STOP** session - handoff only
5. This skill body is **English**; user-facing prompts may be **(pt-BR)**

### Step -1 - Gate check (report in chat before continuing)

```
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] PIPELINE.md read (SDD skills only)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
```

---

# Skill: document-plan

## Trigger
**Negative signal:** Do not activate this skill when the request lacks one of the positive signals below or its required context; topic similarity or an isolated keyword alone is insufficient.


Invoke when the user asks for: `/document-plan`, `plan repo documentation`, `/document-plan`, or `doc plan`.

Optional argument: path to an existing **reviewed** `docs/overview.md` (or equivalent) to seed the plan.

## Outcome

In the **target workspace** (not this toolkit repo unless that is the repo to document):

- `docs/documentation-plan/plan.md` - baby-step documentation plan with progress tracking
- `docs/overview.md` - high-level repo summary (created or refreshed unless user supplied overview)

Product documentation prose follows the **language the user chooses** (pt-BR or English). File paths stay in English.

## Lazy-load

| When | Path |
|------|------|
| Caveman Mode (if active) | `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md` - **Lite cap** |
| Reference index (routing only) | `{{TOOLKIT_ROOT}}/skills/document-plan/reference.md` |
| Process step detail (lazy) | `{{TOOLKIT_ROOT}}/skills/document-plan/references/<section>.md` |
| SDD vs RAG plan boundary | `{{TOOLKIT_ROOT}}/skills/_shared/sdd-artifacts/STORAGE.md` (read section Read-only discovery - do not conflate paths) |
| Language surfaces (chat vs spawn) | `{{TOOLKIT_ROOT}}/skills/_shared/agents/LANGUAGE.md` |

**Never by default:** do not preload full `reference.md` when `references/` exists; load one section per Process step (`SKILL-REFERENCE-RETRIEVAL.md`).

## Reference routing

| Situation | Path |
|-----------|------|
| Stack detection | `references/stack-detection.md` |
| Output paths | `references/output-paths.md` |
| Plan template | `references/plan-template.md` |
| Execution update / SDD boundary | `references/execution-update.md` |
| Planning checklist | `references/planning-checklist.md` |
## Process

### Step -1b - Caveman Mode (Lite cap)
1. Read `{{SDD_ROOT}}/preferences.json` (create `{ "caveman_mode": false, "caveman_level": "full" }` if missing).
2. If `caveman_mode` is false: continue without compression.
3. If true: load `{{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md`; apply **Lite** participation cap + prefs `caveman_level` (Lite skills never escalate); show once: `[Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.`
4. Honor `caveman on|off|status|lite|full|ultra` (and `stop caveman` / `normal mode`) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per `CAVEMAN.md`.

### 0. Workspace and stack

1. Confirm **target repository** (consumer app/service - not the toolkit unless explicit).
2. Detect stack with Glob (see `references/stack-detection.md`). Summarize: languages, frameworks, layout - **do not** assume a fixed corporate stack.
3. Read `AGENTS.md` / `README.md` if present.

**Not SDD:** this skill writes `docs/documentation-plan/plan.md` only - not `PLAN/PLAN_*.md` or `{{SDD_ROOT}}/<repo-id>/PLAN/`. Feature PRD/PLAN use `sdd-spec` / `sdd-plan` / `sdd-develop` per `STORAGE.md`.

### 1. Documentation language (blocker)

Before creating or updating any file under `docs/` in the target repo, ask once:

> Documentation language for product `docs/` - **pt-BR** or **English**?

Record the choice in the session and in `docs/documentation-plan/plan.md` header (see template).

### 2. Existing artifacts

| Path | Action |
|------|--------|
| `docs/documentation-plan/plan.md` | If exists: read completed steps; resume or ask to overwrite |
| `docs/overview.md` | Use user-provided path, existing file, or generate from exploration |
| Neither | Create both per `references/output-paths.md` + `references/plan-template.md` |

### 3. Explore and draft overview

Glob/Grep/Read: solution layout, main entry points, bounded contexts, external integrations, test layout. Write or update `docs/overview.md` in the chosen language - concise, RAG-friendly, no invented business domain names.

### 4. Write documentation plan

Create or update `docs/documentation-plan/plan.md` using `references/plan-template.md` (checklist: `references/planning-checklist.md`):

**Sizing (required):**

| Kind | How to plan |
|------|-------------|
| **New** domain/overview/integration doc (file does not exist yet) | **One plan step per new deliverable file** (e.g. one step → `docs/domains/billing.md`) |
| **Update** existing docs after a feature/change | Prefer **one single update step** covering all touched existing paths (not one baby-step per file) |
| Large greenfield pack or large doc refactor | Keep coherent steps; `document-implement` may **spawn** specialists for heavy steps (`SPAWN.md`) |

Do **not** default to 5–12 tiny baby steps. Prefer fewer, larger steps aligned with new files + one update bucket when refreshing.

- Progress `0/N`, status per step (**Pending** / **Completed**)
- Mark **Kind:** `new` \| `update` \| `refactor` on each step when useful for implement routing
- Each **new**-doc step sized for one `document-implement` session; **update** steps may list multiple existing paths in one session

### 5. Context checkpoint

Checkpoint durable workflow progress at the workflow-defined boundaries; context usage does not add a stop gate.

### 6. Summarize handoff

Report: paths written, language, step count, first pending step id.

```
/document-implement
```

## Must not

- Embed MES, Athena, or organization-specific product context
- Require external wiki APIs, or fixed .NET/Angular versions without detection
- Create `docs/documentation-plan/` inside **this toolkit repo** during porting (only in consumer repos at runtime)
- Write `docs/` before the language question is answered
- Default product doc language without asking

## Handoff

| Situation | Next |
|-----------|------|
| Execute next doc step | `/document-implement` |
| Code change needed | `/developer` or SDD `sdd-develop` |
| Commit docs | `/commit` |

• SKILL.md 7 KB
• reference.md 1 KB
• references/execution-update.md 1 KB
• references/output-paths.md 1 KB
• references/plan-template.md 3 KB
• references/planning-checklist.md 1 KB
• references/stack-detection.md 1 KB