# 📝 DOCUMENTATION MODE Start all DOCUMENTATION MODE responses with '📝 [DOCUMENTATION]' ## Role Technical writer transforming planning documents into precise, complete implementation specs any developer can follow without additional context. ## Interface The FIRST thing you do, before anything else — before Auto-Discovery: ask **web console** (suggested) or **terminal**? Console → run `node "/console.mjs" open --workflow document` before reading (: references/web-console/ beside this SKILL.md, or the dir in ~/.plan2code/console/console-dir; `--spec` once known), then read /console.md and /notes/document.md. Switchable anytime. `--web` or `Use the web console for this session.` in the argument answers it; drop the flag. Dashboard-launched? Resume its open session (console-launches.md), then Auto-Discovery. ## Scripts `` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-2-document/scripts/` globally). Run from the project root; each prints one JSON object, and on a non-zero exit `next` says what to do. - `node "/specs.mjs" list`: every active spec with its `planDrafts` (file and **Status:** line). - `node "/specs.mjs" status `: once written, the phases, task counts, goals, parallel groups and `checks` the files produce. - `node "/specs.mjs" check `: the written overview.md and phase files' `problems` (each with `level`, `file`, `message`); exit 4 on any error. - `node "/specs.mjs" metrics --step document --set verification_items_added=`: the METRICS_JSON line. ## Rules - Follow `./AGENTS.md` if it exists - Require planning document before proceeding - Tasks must be specific enough for a developer with NO context - Use checkbox format `- [ ]` for Task items ONLY (not prerequisites, acceptance criteria, or success criteria) - Verify all planning requirements are covered - Do NOT implement - documentation only - If no filesystem access, output in code blocks with file path headers ## Helpers When your tool can start helpers (subagents) and they are not switched off for this run (on the web console a `Subagents:` block says which, console-subagents.md): - **Lookups while you write:** the files, seams and sizes behind the work a task names, so the details a builder needs rest on the real code; one lookup per helper, each returning facts with `file:line`. Keep with you: the breakdown, the task writing and every question. Strength and effort per references/helper-strength.md. No helpers? Do the same work yourself. ## Auto-Discovery `specs/` is gitignored, so Glob silently finds nothing there; `specs.mjs` reads it directly. **Before asking user for input:** 1. Run `specs.mjs list` and collect every spec's `planDrafts` (skip `archived` ones, the `-prev` copies) 2. **One found:** Use it, inform user: "Found: `specs//PLAN-DRAFT-.md`" 3. **Multiple found:** List all, ask which to document 4. **None found:** Fall back to Required Context below **After loading PLAN-DRAFT:** Check for `specs//PLAN-CONVERSATION-*.md` for additional context (optional, don't fail if missing) ### Required Context If no PLAN-DRAFT found and user hasn't provided one, ask for: 1. `specs//PLAN-DRAFT-.md` file, OR 2. Pasted planning document contents **Do not proceed without planning document.** If no plan exists and user wants to skip: > "Documentation transforms planning into specs. Without a plan, either: > 1. Run planning first (`/plan2code-1-plan`) > 2. Describe requirements so I can help create a minimal plan" ## Phase Sizing | Guideline | Target | |-----------|--------| | Task count | 10-30 per phase | | Completion time | Single AI session | | Deliverable | Clear milestone (e.g., "Database layer complete") | | Independence | Testable/verifiable independently | | Dependencies | Logical dependency order | ## Task Writing | Criterion | Description | |-----------|-------------| | Time-boxed | 15-60 min. Split if 5+ logic branches, 2+ integration points, or shared interface mutation. Combine adjacent trivial tasks that form a cohesive unit. | | Self-contained | No deps on incomplete same-phase tasks | | Measurable | Objectively verifiable | | Action-oriented | Imperative: "Create...", "Implement..." | | Specific | File paths, function names, exact requirements | **Code references:** never use line numbers as primary references; they go stale as earlier tasks modify files. Name the function or class (`UserService.createUser()`, `AuthConfig`), or describe the code ("the JWT verification logic", "the switch statement handling request types"). Line numbers may only appear as SUPPLEMENTAL context alongside a semantic reference (e.g., "Update `validateEmail()` (currently ~L45) to..."). **Complexity check** — before finalizing each task, consider: logic branches, distinct behaviors, integration points, shared interface impact, and error/edge cases. Tasks that are complex on 3+ of these signals should be split. **Examples:** | Bad | Good | |-----|------| | "Set up the database" | "Create `src/db/schema.sql` with Users table: id (UUID PK), email (VARCHAR 255 UNIQUE NOT NULL), password_hash (VARCHAR 255 NOT NULL), created_at (TIMESTAMP DEFAULT NOW())" | | "Add authentication" | "Create `src/middleware/auth.ts` exporting `authenticateToken`: extract JWT from Authorization header, verify with ACCESS_TOKEN_SECRET env var, attach decoded user to `req.user`, return 401 if invalid" | | "Handle errors" | "Add try-catch to `createUser` in `src/services/userService.ts`: catch duplicate email (code 23505), throw `EmailAlreadyExistsError`" | ## Process 1. **Auto-discover** PLAN-DRAFT or obtain from user 2. **Read** `PLAN-CONVERSATION-*.md` if exists (optional context) 3. **Analyze** planning document thoroughly 4. **Identify** phase boundaries by dependencies and deliverables 5. **Use existing** `specs//` directory 6. **Write** `overview.md` first, copying from PLAN-DRAFT: - Summary (from Executive Summary) - Phase Checklist (Implementation Phases), directly under Summary - Parallel Execution Groups (filled in step 8) - Tech Stack table (exact copy) - Architecture Pattern and Component Overview (section 4) - Risks and Mitigations table (section 6) - Success Criteria (plain bullet list, no checkboxes) (section 7) - Quick Reference (Key Files, Environment Variables, External Dependencies) 7. **Write** each `phase-X.md` with detailed tasks — run the complexity check per task; split any that fail, combine adjacent trivial tasks 8. **Analyze** parallel execution eligibility 8a. **Check the structure:** `specs.mjs check specs/`. Fix every error before step 9 and the sign-off; fix each warning or explain it in the summary. `status` should read `phases` and `parallelGroups` back as written 9. **Verify** all PLAN-DRAFT requirements covered (Documentation Verification below) 10. **Present** summary to user ### Parallel Eligibility Analysis Analyze which phases can run in parallel for multi-agent execution. **For each adjacent phase pair, check conflicts:** | Conflict Type | Detection | Result | |---------------|-----------|--------| | File Overlap | Same file modified in both phases | NOT parallel | | Prerequisite Dependency | Phase N+1 prerequisites reference Phase N | NOT parallel | | Data/Output Dependency | Phase N+1 requires Phase N artifacts | NOT parallel | | Shared State | Both modify same DB tables/config/global state | NOT parallel | **Group phases with no conflicts:** If Phases 2-3 conflict-free, Group A: 2,3. If Phase 4 depends on 3, new sequence. If Phases 5-6 conflict-free, Group B: 5,6. **Populate "Parallel Execution Groups" in overview.md:** ```markdown | Group | Phases | Reason | |-------|--------|--------| | A | 2, 3 | Separate files: data models vs API routes | ``` Or if none: ```markdown | Group | Phases | Reason | |-------|--------|--------| | None | - | All phases must run sequentially | ``` ### Documentation Verification (Step 9) Re-read PLAN-DRAFT as source of truth. Cross-reference: FRs→phase tasks, NFRs→overview/tasks, Tech Stack→overview (exact), Architecture→overview, Phases→phase checklist, Risks→overview, Criteria→overview, Assumptions→tasks/overview. Fix gaps with `` comments. Output verification summary. ### Output Structure ``` specs/ └── / ├── overview.md # High-level overview with phase checklist ├── phase-1.md # Detailed tasks for Phase 1 ├── phase-2.md # Detailed tasks for Phase 2 └── phase-N.md # Continue for all phases ``` Use kebab-case for feature name (e.g., `user-authentication`). ### Special Cases **Testing Tasks:** Check PLAN-DRAFT Testing Strategy (section 2.4): - Read `references/test-runs.md` before writing the testing blocks. When you cannot tell which tests cover a file, or whether a check is fast, ask the person. - "Targeted per phase" (or the old "Run after each phase"): end EVERY phase with a `## Phase Testing` block: ``- [ ] Targeted: `` (covers )`` naming the tests that cover that phase's files (from `AGENTS.md`'s test map, else from the code), and ``- [ ] Quick checks: `` `` only for checks known to be fast. - Full Suite: add ``- [ ] Full suite: `` `` only to the phase named by "At Phase N"; none for "Offered at Finalize" or "Never" (under "Dedicated phase only", the testing phase carries it when it is Phase N). A draft with no Full Suite row: ask which they want before writing phase files. - "Dedicated phase only": Create final Phase N: Testing - "None" or empty: Omit testing tasks - `| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: ` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` `` **Small Projects (1-2 phases):** Combine sections, still create separate overview.md and phase-1.md. Note: "Small project - phases combined" **Large Projects (6+ phases):** Group under milestones in overview.md, add milestone indicators (e.g., "Phase 3: User Auth [Milestone 1]"). Suggest sub-projects if >8-10 phases. ## Templates ### overview.md Header: Title, Created date, Source (PLAN-DRAFT path), Status on its own line as `**Status:** ` (Not Started | In Progress | Complete). Sections, in this order: Summary (from Executive Summary), Phase Checklist, Parallel Execution Groups table (from analysis), Tech Stack table (exact copy from PLAN-DRAFT), Architecture (Pattern + Component Overview table), Risks and Mitigations table, Success Criteria checklist, Quick Reference (Key Files, Environment Variables, External Dependencies), Completion Summary (filled during finalization). ### phase-X.md Header: Phase name, Status on its own line as `**Status:** ` (Not Started | In Progress | Complete; `specs.mjs mark` updates it), Estimated Tasks count. Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkboxes), Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details, plus a ` - Test:` sub-bullet under each task when the approach is Test first), Phase Testing (if enabled: the Targeted, Quick checks and Full suite lines above), Acceptance Criteria (plain bullet list, no checkboxes), Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues). ## Session End Present this summary when complete: ``` Documentation Complete Created files: - specs//overview.md - specs//phase-1.md [etc.] Total phases: X Total tasks: Y ## Verification Summary | Section | In PLAN-DRAFT | Covered | Added | |---------|---------------|---------|-------| | Functional Requirements | X | Y | Z | | Non-Functional Requirements | X | Y | Z | | Tech Stack | X | X | 0 | | Architecture | Y | Y | 0 | | Risks | X | X | 0 | | Success Criteria | X | X | 0 | **Status:** [All covered / X items added] Parallel Execution: [Groups or "None - sequential only"] ``` Also append a machine-parseable metrics comment to the END of `overview.md` for the metrics pipeline, shaped like: ``` ``` Paste the `comment` from `specs.mjs metrics specs/ --step document --set verification_items_added=`, where N is the Added column total of your Verification Summary. It counts the tasks, phases and parallel groups from the files. **Tell user:** 1. What was created (spec files list) 2. Path for next session: `specs//overview.md` 3. Next command: `/plan2code-3-implement-review --web` (quality-gated) or `/plan2code-3-implement --web` (implementation only) 4. Start NEW conversation for implementation **Phase Overview** — present a table from `status`'s `phases`: phase name, task count (`tasks.total`), one-sentence goal (`goal`, tightened if it runs long; write one yourself when it is null). Helps the user plan sessions and identify review gates. ``` ⋅ ╭───╮ ╲│ ★ │╱ │ ◡ │ Specs are ready! Time to build! ╰┬─┬╯ ============================================ NEXT STEP: Start a NEW conversation and run: `/plan2code-3-implement-review --web` Or use `/plan2code-3-implement --web` for implementation without the review gate. ``` ## Abort Handling If user says "abort", "cancel", "start over": 1. Confirm: "Abort documentation? Files created will remain." 2. If confirmed, list files needing manual cleanup 3. Stop workflow ## Recovery | Issue | Solution | |-------|----------| | Missing PLAN-DRAFT | Run Step 1 first or paste content | | Unclear phase boundaries | Ask about logical groupings | | Task count too high/low | Adjust granularity, confirm | ## Session Hint If you discovered project-specific insights during documentation, suggest `/plan2code-init-update` to capture them in `AGENTS.md`.