Write Spec

Guidelines for writing and updating specification documents in .workaholic/specs/.

Gather Context

Run the bundled script to collect information about what changed:

bash .claude/skills/write-spec/sh/gather.sh [base-branch]

Default base branch is main.

Output Sections

The script outputs structured information:

=== BRANCH ===
<current branch name>

=== TICKETS ===
<list of archived tickets for this branch, or "No archived tickets">

=== SPECS ===
<list of existing spec files>

=== DIFF ===
<git diff stat against base branch>

=== COMMIT ===
<current short commit hash>

Using the Output

• •BRANCH: Use to locate archived tickets
• •TICKETS: Read these to understand what changed and why
• •SPECS: Survey these to find documents needing updates
• •DIFF: Use when no tickets exist to understand changes
• •COMMIT: Use in frontmatter commit_hash field

Directory Structure

Frontmatter

Required for every spec file:

---
title: Document Title
description: Brief description of this document
category: user | developer
modified_at: <ISO 8601 datetime>
commit_hash: <from context COMMIT section>
---

File Naming

• •Use kebab-case: getting-started.md, command-reference.md
• •Exception: README.md uses uppercase

Content Style

• •Write full paragraphs, not bullet-point fragments
• •Code blocks must specify language
• •Links use relative paths within .workaholic/
• •Use Mermaid charts for diagrams

Design Policy

• •Rewrite to reflect present reality, not append changes
• •Think "what does a new reader need to know today?"

Cross-Cutting Concerns

Before updating individual docs, analyze changes for patterns that span multiple components:

• •Data flow paths: How data moves through layers
• •Shared concepts: Abstractions used across multiple files
• •Integration points: Where different subsystems connect
• •Architectural patterns: Design decisions that affect multiple areas

For each cross-cutting concern:

• •Check if .workaholic/specs/ already has a document covering this concept
• •Prefer extending existing docs over creating new files for minor patterns

Writing cross-cutting documentation:

• •Prefer prose over file listings - explain how components work together
• •Use Mermaid sequence diagrams to show interactions between layers
• •Document the "why" behind design decisions, not just implementation details

Index File Updates

When adding a document:

• •Add link to parent README
• •Include brief description

When removing a document:

• •Remove link from parent README
• •Verify no other docs link to it

i18n README mirroring:

• •Any document added to one README must have its translation linked in the other
• •Follow the preloaded translate skill for translation requirements

Critical Rules

• •"No updates needed" is almost always wrong - Re-analyze if you think nothing changed
• •Every ticket affects docs somehow - Even small changes have documentation implications
• •Only delete within .workaholic/ - Safety constraint for file deletions
• •No orphan documents - Every doc must be linked from a parent README
• •Category matches directory - A doc with category: user must be in guides/, category: developer in specs/
• •Update modified_at - Set to current datetime (use date -Iseconds) when modifying any doc
• •Update commit_hash - Use value from context COMMIT section