Overview

Doc Writer automates creating or refreshing planned and completed task docs using the repository context and the mandated DOC_TEMPLATE.md. It enforces unique two-digit prefixes, follows the exact document structure, and links to existing code or docs rather than duplicating large excerpts. This ensures docs stay consistent, up-to-date, and easy to review in PRs.

How This Skill Works

It reads DOC_TEMPLATE.md and relevant context (PLAN.md, AGENTS.md), determines the next available NN prefix, drafts the required sections (metadata block, Objective, Prerequisites / Dependencies, Implementation Steps, Validation, Completion Criteria, Notes / Follow-ups), and saves the file under docs/planned/ or docs/completed/. It then runs validators (lint/tests) if changes require repository updates and records the commands executed.

When to Use It

• Creating a new task doc from PLAN.md and DOC_TEMPLATE.md to ensure proper structure.
• Updating an existing task doc to reflect repo changes and new requirements.
• Incorporating PLAN.md and AGENTS.md context into a doc without duplicating content.
• Moving a doc from planned to completed after validation and acceptance criteria are met.
• When repository changes require running lint/tests and documenting the commands executed.

Quick Start

1. Step 1: Inspect docs/DOC_TEMPLATE.md and relevant PLAN.md/AGENTS.md to gather context.
2. Step 2: Determine the next available two-digit NN prefix and draft sections per the template.
3. Step 3: Save to docs/planned/ or docs/completed/, run validators, and summarize in PR notes.

Best Practices

• Ensure the two-digit NN prefix is unique by scanning existing docs before drafting.
• Draft using the exact sections defined in the template: metadata block, Objective, Prerequisites / Dependencies, Implementation Steps, Validation, Completion Criteria, Notes / Follow-ups.
• Link to existing code or documentation via relative paths rather than copying large excerpts.
• Verify acceptance criteria reflect the latest repo state (tests, tooling, env requirements) before finalizing.
• Run required validators (lint/tests) if updates mandate repo changes and clearly record the commands executed.

Example Use Cases

• docs/planned/03-user-auth-flow.md created from PLAN.md and DOC_TEMPLATE.md.
• docs/planned/04-ci-cd-pipeline.md drafted with references to AGENTS.md and CODE links.
• docs/planned/05-data-ingestion.md created, linking to src/data ingestion files.
• docs/completed/01-setup-minimal-env.md updated after validation and tests pass.
• docs/completed/02-integration-tests.md updated following test run results.

Frequently Asked Questions