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 tablesNo emojis - ASCII only, no `---` markers between sectionsHeader block: Doc ID (required), Goal (required), Target file, Depends on (omit if N/A)Every document MUST have a unique IDReference other docs by filename AND Doc ID: `_SPEC_CRAWLER.md [CRWL-SP01]`Be exhaustive: list ALL domain objects, actions, functionsDocument History section at end, reverse chronologicalUse box-drawing characters (├── └── │) for treesSPEC, 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` - AGEN verb workflow structure`STRUT_TEMPLATE.md` - STRUT plans (embeddable in any document)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 firstAgent 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 AGEN Verb Workflows
AGEN verbs map directly to Windsurf workflows. See `WORKFLOW_TEMPLATE.md` for:
Workflow structure templateGeneral vs Specific parts patternContext discovery patternStrategy patternOutput rules