Work Item Writer

Write work items with clear descriptions and actionable acceptance criteria.

Quick Reference

bash
1govctl work new --active "<title>"
2govctl work set <WI-ID> description "Task scope description"
3govctl work add <WI-ID> acceptance_criteria "<category>: <description>"
4govctl work add <WI-ID> journal "Progress update" --scope module
5govctl work add <WI-ID> notes "Key observation"
6govctl work add <WI-ID> refs RFC-NNNN
7govctl work tick <WI-ID> acceptance_criteria "<pattern>" -s done
8govctl 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

bash
1# Add journal entry (date is auto-filled to today)
2govctl work add <WI-ID> journal "Added journal section rendering to work item output."
3
4# With scope (topic/module tag)
5govctl work add <WI-ID> journal "Fixed parser edge case" --scope parser
6
7# Multi-line via stdin
8govctl work add <WI-ID> journal --scope render --stdin <<'EOF'
9Completed the rendering pipeline.
10All snapshot tests updated.
11EOF

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

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

Acceptance Criteria

Every criterion MUST have a category prefix for changelog generation:

bash
1# Feature work
2govctl work add <WI-ID> acceptance_criteria "add: Implement clause validation"
3govctl work add <WI-ID> acceptance_criteria "add: Error messages include clause ID"
4
5# Bug fix
6govctl work add <WI-ID> acceptance_criteria "fix: Duplicate clause detection"
7
8# Internal
9govctl work add <WI-ID> acceptance_criteria "chore: All tests pass"
10govctl work add <WI-ID> acceptance_criteria "chore: govctl check passes"

References

Link to governing artifacts:

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

Field Semantics Summary

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:

bash
1# Tick criteria as you complete them
2govctl work tick <WI-ID> acceptance_criteria "<pattern>" -s done
3
4# When all criteria are done, close the work item
5govctl work move <WI-ID> done

The chore: Pattern

Always add at least one chore: criterion for validation:

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

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

Common Mistakes