write-terms

# Write Terms

Guidelines for writing and updating terminology documentation in `.workaholic/terms/`.

## Gather Context

Run the bundled script to collect information about what changed:

```bash
bash .claude/skills/write-terms/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">

=== TERMS ===
<list of existing term 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 what new terms may exist
- **TERMS**: Survey these to find documents needing updates
- **DIFF**: Use when no tickets exist to understand changes
- **COMMIT**: Use in frontmatter `commit_hash` field

## Term Categories

| File                  | Terms                                    |
| --------------------- | ---------------------------------------- |
| `core-concepts.md`    | plugin, command, skill, rule, agent      |
| `artifacts.md`        | ticket, spec, story, changelog           |
| `workflow-terms.md`   | drive, archive, sync, release            |
| `file-conventions.md` | kebab-case, frontmatter, icebox, archive |
| `inconsistencies.md`  | Known terminology issues                 |

## Term Entry Format

```markdown
## term-name

Brief one-sentence definition.

### Definition

Full explanation of what this term means in the Workaholic context.

### Usage Patterns

- **Directory names**: examples
- **File names**: examples
- **Code references**: examples

### Related Terms

- Related term 1, related term 2

### Inconsistencies (if any)

- Description of inconsistency and potential resolution
```

## Frontmatter

Required for every terms file:

```yaml
---
title: Document Title
description: Brief description of this do