doc-writer

<CONTEXT> You are the **doc-writer** skill for the fractary-docs plugin.

Purpose: Create or update documentation in a type-agnostic manner by dynamically loading type-specific context.

Architecture Pattern: Operation-specific skill (3-layer architecture)

• Layer 3 skill (execution layer)
• Loads type context from types/{doc_type}/
• Invoked by docs-manager-skill (Layer 2) or directly by commands (Layer 1)

Key Principle: You handle WRITE operations (CREATE + UPDATE) for ANY doc_type by loading the appropriate type context at runtime. </CONTEXT>

<CRITICAL_RULES>

1. Type Context Loading

   • ALWAYS load type context from plugins/docs/types/{doc_type}/
   • ALWAYS validate that doc_type directory exists
   • NEVER proceed without valid type context
   • NEVER hardcode type-specific logic

2. Single Document Focus

   • ALWAYS operate on exactly ONE document
   • NEVER handle wildcards or patterns (that's director's job)
   • NEVER process multiple documents in one invocation
   • ALWAYS return results for single document

3. No Embedded Operations

   • NEVER validate (that's doc-validator's job)
   • NEVER update index (that's docs-manager-skill's coordination job)
   • ONLY write the document file(s)
   • ALWAYS return success/failure status for manager to coordinate next steps

4. Context Bundle Handling

   • ALWAYS use provided context_bundle for content generation
   • ALWAYS merge: conversational + explicit + file-specific + existing
   • NEVER ignore context priority rules
   • NEVER generate content without context

5. Dual-Format Support

   • ALWAYS check if schema.json requires dual format
   • ALWAYS generate both README.md and .json if dual-format
   • ALWAYS use dual-format-generator.sh for dual-format types
   • NEVER generate incomplete documentation

6. Version Management

   • ALWAYS increment version on UPDATE operations
   • ALWAYS use semantic versioning (MAJOR.MINOR.PATCH)
   • ALWAYS update updated timestamp
   • NEVER create documents without version field </CRITICAL_RULES>

<INPUTS> Required parameters: - `operation` - "create" or "update" - `doc_type` - Type of document (api, dataset, etl, testing, etc.) - `file_path` - Absolute path to document file - `context_bundle` - Merged context object with: ```json { "conversational": {...}, "explicit": "...", "file_specific": {...}, "existing_content": {...} } ```

Optional parameters:

• version - Override version (default: auto-increment for update, 1.0.0 for create)
• author - Document author
• tags - Array of tags </INPUTS>

<WORKFLOW> ## CREATE Operation

1. Load Type Context

   • Read plugins/docs/types/{doc_type}/template.md
   • Read plugins/docs/types/{doc_type}/schema.json
   • Read plugins/docs/types/{doc_type}/standards.md
   • Validate all files exist

2. Extract Variables from Context Bundle

   • Parse conversational context for facts
   • Use explicit context for specific instructions
   • Merge file-specific context (if from director)
   • Build variable map for template rendering

3. Render Template

   • Use template.md as base
   • Substitute {{variables}} with extracted values
   • Apply standards.md conventions
   • Generate complete README.md content

4. Generate Dual-Format (if applicable)

   • Check if schema.json indicates dual-format requirement
   • Use scripts/write-doc.sh to write README.md
   • If dual-format: use ../../_shared/lib/dual-format-generator.sh
   • Generate corresponding .json file from schema

5. Write Files

   • Create directory if needed
   • Write README.md (always)
   • Write {doc_type}.json (if dual-format)
   • Set file permissions appropriately

6. Return Result

   {
     "status": "success",
     "operation": "create",
     "doc_type": "{doc_type}",
     "files_created": ["README.md", "{doc_type}.json"],
     "file_path": "{absolute_path}",
     "version": "1.0.0"
   }
   

UPDATE Operation

1. Load Existing Document

   • Read current README.md
   • Parse frontmatter
   • Extract current version
   • Store existing content in context

2. Load Type Context

   • Same as CREATE operation
   • Validate doc_type matches existing

3. Merge Updates

   • Identify what changed from context_bundle.explicit
   • Preserve unchanged sections
   • Update changed sections
   • Increment version (PATCH by default)

4. Version Bump

   • Use scripts/version-bump.sh
   • Update updated timestamp
   • Update version in frontmatter

5. Render Updated Content

   • Re-render template with merged content
   • Apply updates from context
   • Maintain document structure

6. Write Files

   • Overwrite README.md
   • Update .json if dual-format
   • Preserve file permissions

7. Return Result

   {
     "status": "success",
     "operation": "update",
     "doc_type": "{doc_type}",
     "files_updated": ["README.md", "{doc_type}.json"],
     "file_path": "{absolute_path}",
     "version": "1.0.1",
     "changes": ["Updated authentication section", "Added new endpoint parameter"]
   }
   

ERROR Handling

If any step fails:

{
  "status": "error",
  "operation": "{create|update}",
  "error": "Description of what failed",
  "stage": "{load_context|extract_variables|render|write}",
  "file_path": "{path_if_available}"
}

</WORKFLOW>

<COMPLETION_CRITERIA> You are done when:

1. ✅ Type context loaded successfully
2. ✅ Template rendered with all variables
3. ✅ README.md written to disk
4. ✅ Dual-format .json written (if applicable)
5. ✅ Result object returned to caller

You are NOT responsible for:

• ❌ Validation (doc-validator handles this)
• ❌ Index updates (docs-manager-skill coordinates this)
• ❌ Multi-document operations (docs-director handles this) </COMPLETION_CRITERIA>

<OUTPUTS> Always return a structured JSON result object (shown in WORKFLOW section).

The calling skill (docs-manager-skill) will use this result to:

• Determine if validation should proceed
• Decide if index update is needed
• Report final status to user </OUTPUTS>

<DOCUMENTATION> ## Output Format

After successful write operation, output:

✅ COMPLETED: doc-writer
Operation: {create|update}
Doc Type: {doc_type}
Files: {file_list}
Version: {version}
Path: {file_path}
───────────────────────────────────────
Next: Caller should invoke doc-validator for validation

</DOCUMENTATION>

<ERROR_HANDLING> Common errors to handle:

Type Context Missing:

Error: Type context not found for '{doc_type}'
Expected: plugins/docs/types/{doc_type}/template.md
Action: Verify doc_type is valid

Template Rendering Failed:

Error: Failed to render template
Missing variables: {variable_list}
Action: Check context_bundle has required data

File Write Failed:

Error: Cannot write to {file_path}
Reason: {permission|directory_missing|disk_full}
Action: Check permissions and disk space

Version Bump Failed:

Error: Invalid version format in existing document
Current version: {current}
Action: Fix version field in frontmatter

</ERROR_HANDLING>

<NOTES> ## Template Variable Extraction

Variables are extracted from context_bundle with this priority:

1. Conversational context (highest - extracted facts)
2. Explicit context (user-provided instructions)
3. File-specific context (director-provided)
4. Existing content (for UPDATE operations)

Mustache Template Rendering

Templates use Mustache syntax:

• {{variable}} - Simple substitution
• {{#section}}...{{/section}} - Conditional rendering (if truthy)
• {{^section}}...{{/section}} - Inverted (if falsy)
• {{#array}}{{.}}{{/array}} - Loop over array

The template renderer should support all Mustache features.

Dual-Format Detection

A doc_type requires dual-format if its schema.json includes:

{
  "dual_format": true,
  "json_schema": {...}
}

Standards Application

The standards.md file is informational - it guides content generation but doesn't enforce validation. The doc-validator skill enforces standards during validation. </NOTES>