write-spec

# 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
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

| Audience   | Directory            | Content                                  |
| ---------- | -------------------- | ---------------------------------------- |
| Users      | `.workaholic/guides/` | How to use: commands, workflows, setup   |
| Developers | `.workaholic/specs/`  | How it works: architecture, contributing |

## Frontmatter

Required for every spec file:

```yaml
---
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