---

name: wi-writer description: "Write well-structured work items with proper acceptance criteria. Use when: (1) Creating work items, (2) Adding acceptance criteria, (3) User mentions work item, task, WI, or ticket"

Work Item Writer

Write work items with clear descriptions and actionable acceptance criteria.

Quick Reference

govctl work new --active "<title>"
govctl work set <WI-ID> description "Task scope description"
govctl work add <WI-ID> acceptance_criteria "<category>: <description>"
govctl work add <WI-ID> journal "Progress update" --scope module
govctl work add <WI-ID> notes "Key observation"
govctl work add <WI-ID> refs RFC-NNNN
govctl work tick <WI-ID> acceptance_criteria "<pattern>" -s done
govctl work move <WI-ID> done

Work Item Structure

Title

Concise, action-oriented. Describes what will be done.

• Good: "Add validation for clause cross-references"
• Bad: "Fix stuff" or "Work on the thing"

Description

Purpose: Task scope declaration — what needs to be done.

Replace the placeholder immediately. One paragraph explaining:

• What the work accomplishes
• Why it's needed
• Any relevant context

Important: Description is for task scope, NOT execution tracking. Use journal for progress and outcomes, and notes for durable learnings.

Journal

Purpose: Execution process tracking — how the work is progressing.

Journal entries record progress updates, bug fixes, and verification results during execution. Each entry has:

• date (required): ISO date "YYYY-MM-DD"
• scope (optional): Topic/module identifier
• content (required): Markdown text with details

# Add journal entry (date is auto-filled to today)
govctl work add <WI-ID> journal "Added journal section rendering to work item output."

# With scope (topic/module tag)
govctl work add <WI-ID> journal "Fixed parser edge case" --scope parser

# Multi-line via stdin
govctl work add <WI-ID> journal --scope render --stdin <<'EOF'
Completed the rendering pipeline.
All snapshot tests updated.
EOF

When to add journal entries:

• After completing a significant chunk of work
• When fixing bugs during implementation
• After running verification gates
• After a failed attempt that changed the next step

Notes

Purpose: Durable learnings — constraints, decisions, and retry rules to remember before the next step.

Notes are concise points recorded anytime, not just at completion. Use for:

• Why an approach failed
• What not to retry
• Constraints or decisions future steps must obey

govctl work add <WI-ID> notes "Remember to update migration guide"
govctl work add <WI-ID> notes "API is now async"

Acceptance Criteria

Every criterion MUST have a category prefix for changelog generation:

| Prefix | Changelog Section | Aliases | | ------------ | ----------------- | --------------------------------- | | add: | Added | feat:, feature:, added: | | fix: | Fixed | fixed: | | change: | Changed | changed:, refactor:, perf: | | remove: | Removed | removed: | | deprecate: | Deprecated | deprecated: | | security: | Security | sec: | | chore: | (excluded) | test:, docs:, ci:, build: |

# Feature work
govctl work add <WI-ID> acceptance_criteria "add: Implement clause validation"
govctl work add <WI-ID> acceptance_criteria "add: Error messages include clause ID"

# Bug fix
govctl work add <WI-ID> acceptance_criteria "fix: Duplicate clause detection"

# Internal
govctl work add <WI-ID> acceptance_criteria "chore: All tests pass"
govctl work add <WI-ID> acceptance_criteria "chore: govctl check passes"

References

Link to governing artifacts:

govctl work add <WI-ID> refs RFC-0001
govctl work add <WI-ID> refs ADR-0023

Field Semantics Summary

| Field | Purpose | Update Pattern | | --------------------- | -------------------------- | --------------------------------------------- | | description | Task scope declaration | Define once, rarely change | | journal | Execution process tracking | Append on each progress | | notes | Durable learnings | Add when future steps must remember something | | acceptance_criteria | Completion criteria | Define then tick |

Per ADR-0026: Keep description focused on "what", journal on "what happened", and notes on "what to remember next".

Writing Rules

Acceptance Criteria Quality

Each criterion should be:

• Specific — "Add validate_refs() function" not "Add validation"
• Testable — Can be verified as done/not-done with no ambiguity
• Independent — Each criterion stands alone
• Categorized — Always include the category prefix

Completion Flow

Work items cannot be marked done without ticking all criteria:

# Tick criteria as you complete them
govctl work tick <WI-ID> acceptance_criteria "<pattern>" -s done

# When all criteria are done, close the work item
govctl work move <WI-ID> done

The chore: Pattern

Always add at least one chore: criterion for validation:

govctl work add <WI-ID> acceptance_criteria "chore: govctl check passes"

This ensures validation is an explicit gate, not an afterthought.

Common Mistakes

| Mistake | Fix | | -------------------------------- | ----------------------------------------------------------- | | Missing category prefix | Always use add:, fix:, chore:, etc. | | Placeholder description left in | Replace immediately with real description | | Vague criteria: "Feature works" | Specific: "add: CLI returns exit code 0 on success" | | No chore: criterion | Add "chore: govctl check passes" or "chore: all tests pass" | | No refs to governing artifacts | Link RFCs/ADRs with work add <WI-ID> refs | | Description used for tracking | Use journal field for execution progress per ADR-0026 | | No journal entries for long task | Add journal entries for significant progress updates |