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 - 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 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 AGEN Verb Workflows

AGEN verbs map directly to Windsurf workflows. See WORKFLOW_TEMPLATE.md for:

• •Workflow structure template
• •General vs Specific parts pattern
• •Context discovery pattern
• •Strategy pattern
• •Output rules