@karstenheld3/write-documents

---
name: write-documents
description: Apply when creating or editing INFO, SPEC, IMPL, TEST, FIX documents, or STRUT plans
---

# Document Writing Guide

This skill contains document templates and formatting rules.

## Verb Mapping

This skill implements:
- [WRITE-INFO] - Create INFO documents (use INFO_TEMPLATE.md)
- [WRITE-SPEC] - Create SPEC documents (use SPEC_TEMPLATE.md)
- [WRITE-IMPL-PLAN] - Create IMPL documents (use IMPL_TEMPLATE.md)
- [WRITE-TEST-PLAN] - Create TEST documents (use TEST_TEMPLATE.md)
- [WRITE-FIX] - Create FIX documents (use FIXES_TEMPLATE.md)
- [WRITE-FAIL] - Create/update FAILS.md (use FAILS_TEMPLATE.md)
- [WRITE-REVIEW] - Create _REVIEW.md documents (use REVIEW_TEMPLATE.md)
- [WRITE-TASKS-PLAN] - Create TASKS documents (use TASKS_TEMPLATE.md)
- [WRITE-STRUT] - Create/insert STRUT plans (use STRUT_TEMPLATE.md)

## MUST-NOT-FORGET

- Use lists, not Markdown tables
- No emojis - ASCII only, no `---` markers between sections
- Header block: Doc ID (required), Goal (required), Target file, Depends on (omit if N/A)
- Every document MUST have a unique ID
- Reference other docs by filename AND Doc ID: `_SPEC_CRAWLER.md [CRWL-SP01]`
- Be exhaustive: list ALL domain objects, actions, functions
- Document History section at end, reverse chronological
- Use box-drawing characters (├── └── │) for trees
- SPEC, IMPL, TEST documents MUST have MUST-NOT-FORGET section (after header block, before TOC)

## Document Writing Rules

- Enumerations: use comma-separated format (`.pdf, .docx, .ppt`), NOT slash-separated (`.pdf/.docx/.ppt`)
- Ambiguous modifiers: when a clause can attach to multiple nouns, split into separate sentences
  - BAD: "Files starting with '!' signify high relevance that must be treated with extra attention."
  - GOOD: "Files starting with '!' indicate high relevance. This information must be treated with extra attention."

## Templates (Required)

You MUST read the appropriate template before creating documents:
- `INFO_TEMPLATE.md` - Research and analysis documents
- `SPEC_TEMPLATE.md` - Technical specifications
- `IMPL_TEMPLATE.md` - Implementation plans
- `TEST_TEMPLATE.md` - Test plans
- `TASKS_TEMPLATE.md` - Task plans (partitioned work items)
- `FIXES_TEMPLATE.md` - Fix tracking documents
- `FAILS_TEMPLATE.md` - Failure log (lessons learned)
- `REVIEW_TEMPLATE.md` - Review documents (_REVIEW.md)
- `WORKFLOW_TEMPLATE.md` - Workflow structure template
- `STRUT_TEMPLATE.md` - STRUT plans (embeddable in any document)

## Session Tracking Templates

For session tracking files (NOTES.md, PROBLEMS.md, PROGRESS.md), use templates from @session-management skill:
- `NOTES_TEMPLATE.md` - Session notes and context
- `PROBLEMS_TEMPLATE.md` - Problem tracking
- `PROGRESS_TEMPLATE.md` - Progress tracking

## Usage

1. Read this SKILL.md for core rules
2. Read the template for your document type (required)
3. For SPEC documents: also read `SPEC_RULES.md` (required)
4. Follow the template structure exactly, except when user requests exceptions or different structure

## File Naming

- `_INFO_[TOPIC].md` - Research, analysis, preparation documents
- `_SPEC_[COMPONENT].md` - Technical specifications
- `_SPEC_[COMPONENT]_UI.md` - UI specifications
- `_IMPL_[COMPONENT].md` - Implementation plans
- `_IMPL_[COMPONENT]_FIXES.md` - Fix tracking during implementation
- `SPEC_[COMPONENT]_TEST.md` - Test plan for specification
- `IMPL_[COMPONENT]_TEST.md` - Test plan for implementation
- `TASKS_[TOPIC].md` - Task plans (partitioned work items)
- `!` prefix for priority docs that must be read first

## Agent Behavior

- Be extremely concise. Sacrifice grammar for concision.
- NEVER ask for continuations when following plans.
- Before assumptions, propose 2-3 implementation alternatives.
- List assumptions at spec start for user verification.
- Optimize for simplicity.
- Re-use existing code by default (DRY principle).
- Research APIs before suggesting; rely on primary sources only.
- Document user decisions in "Key Mechanisms" and "What we don't want" sections.

## ID System

See `[AGENT_FOLDER]/rules/devsystem-ids.md` rule (always-on) for complete ID system.

**Quick Reference:**
- Document: `[TOPIC]-[DOC][NN]` (IN = Info, SP = Spec, IP = Impl Plan, TP = Test Plan)
  - Example: `CRWL-SP01`, `AUTH-IP01`
- Spec-Level: `[TOPIC]-[TYPE]-[NN]` (FR = Functional Requirement, IG = Implementation Guarantee, DD = Design Decision)
  - Example: `CRWL-FR-01`, `AUTH-DD-03`
- Plan-Level: `[TOPIC]-[DOC][NN]-[TYPE]-[NN]` (EC = Edge Case, IS = Implementation Step, VC = Verification Checklist, TC = Test Case)
  - Example: `CRWL-IP01-EC-01`, `AUTH-TP01-TC-05`

## Writing Workflows

See `WORKFLOW_TEMPLATE.md` for:
- Workflow structure template
- General vs Specific parts pattern
- Context discovery pattern
- Strategy pattern
- Output rules