wi-writer

Work Item Writer

Write work items with clear descriptions and actionable acceptance criteria.

Invocation Mode

This helper skill may be used standalone or by /gov, /quick, or /commit. It is responsible for work-item content quality and field semantics, not code changes or VCS operations.

Authority

Work items track durable operational state: task scope, lifecycle, acceptance criteria, dependencies, references, and notes that should remain after closure. They are operational memory, not normative authority and not decision records.

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> notes "Durable constraint or retry rule"
govctl work add <WI-ID> refs RFC-NNNN
govctl work add <WI-ID> depends_on <BLOCKING-WI-ID>
govctl work add <WI-ID> tags <tag>
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 loop state and round artifacts for execution trace, and notes only for closure-worthy durable learnings that belong on the work item. It must not introduce new product behavior requirements that are missing from the governing RFC or ADR.

Execution Trace

Where execution information goes now:

• Round-by-round execution trace belongs in loop state and round artifacts.
• Durable lessons, constraints, and retry rules that should still matter after closure belong in notes.
• Acceptance progress belongs in acceptance_criteria status.

Notes

Purpose: Closure-worthy durable context — stable constraints, decisions, and retry rules that should remain useful after the work item is done.

Use notes sparingly for:

• Why an approach must not be retried because of a stable technical reason
• Constraints or decisions future maintainers must obey
• Important implementation facts that are not obvious from the final diff

These notes may explain local execution constraints, but they do not override RFCs or accepted ADRs. Do not use notes for progress updates, commands run, validation output, current plans, next actions, temporary blockers, hypotheses, review status, or "remember to do X" TODOs.

govctl work add <WI-ID> notes "Do not retry the legacy JSON migration path; v0.9 intentionally rejects it"
govctl work add <WI-ID> notes "Legacy inline journal entries must remain render-only for older work items"

Acceptance Criteria

Every criterion MUST have a category prefix for changelog generation:

# 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

Dependencies and Batches

Create multiple work items only when each item is independently meaningful to future readers:

• Each work item should represent a durable outcome, user-visible behavior, spec/ADR obligation, or independently reviewable deliverable.
• Do not create work items for mechanical helper extraction, fixture sharing, file moves, module normalization, formatting, comment cleanup, snapshot reshaping, or other low-level execution steps.
• For trivial cleanup or docs-only edits, no work item may be the right answer; follow the invoking workflow instead of inventing tracking.
• For one coherent cleanup/refactor, prefer one coarse work item over many narrow slices.
• Use depends_on only for hard execution ordering; keep refs for informational links.
• Use a loop for non-trivial governed execution that needs local execution memory, including single-work-item execution after journal-style trace moved out of Work Item fields.
• Use one multi-work-item loop only when there are multiple durable work items; do not use loops to justify creating mechanical work-item fragments.
• Let govctl generate the loop ID with govctl loop start <ROOT-WI-ID> [<ROOT-WI-ID>...]; use the returned LOOP-YYYY-MM-DD-NNN ID for later loop commands.
• Use govctl loop list open to discover existing non-terminal loops before resuming interrupted batch work.

If the batch scope changes after the loop starts, update the same loop:

govctl loop add <LOOP-ID> work <ROOT-WI-ID>
govctl loop remove <LOOP-ID> work <ROOT-WI-ID>
govctl loop replan <LOOP-ID>

work is the editable loop work-item field. wi is accepted as a short alias, but examples should prefer work.

Do not hand-write descriptive loop IDs or encode time finer than the day in loop IDs.

Field Semantics Summary

Per ADR-0047: Keep description focused on "what", notes on closure-worthy durable context, and execution trace outside the work item field surface. If you discover a missing requirement or unresolved design choice, stop and route that back to RFC/ADR work rather than inventing it inside the work item.

Writing Rules

Authority Test

Before adding description, notes, or acceptance criteria, apply these checks:

• Task scope: Work item fields describe what this task must complete, not the product contract itself.
• Governing refs: New user-visible behavior, CLI behavior, storage format, validation rule, compatibility rule, or lifecycle rule must be backed by RFC/ADR refs.
• Design destination: If the text explains why a design option was chosen, move it to an ADR.
• Execution destination: If the text records progress, commands run, validation output, review status, temporary blockers, hypotheses, or next actions, move it to loop state, round artifacts, or the final response.
• Durability: Keep notes only when the fact should remain useful after the work item is closed.

Examples:

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.

Guardable Command Checks

Prefer verification guards over plain acceptance criteria for repeatable command-style checks. When a criterion is only "cargo test passes", "clippy passes", or another shell command succeeds, first check whether an existing guard already covers it. If so, require that guard through the work item's [verification] section instead of duplicating the command as a behavioral acceptance criterion. Use verification.required_guards for per-work-item guard requirements.

Project-level verification.default_guards apply broadly to work-item completion when verification is enabled. Use work-item-level verification.required_guards to add task-specific guards on top of those defaults, not to repeat guards that already apply globally. Waivers apply to the effective guard set: project defaults plus work-item-specific required guards.

[verification]
required_guards = ["GUARD-CARGO-TEST"]

Use acceptance criteria for observable task outcomes. Keep chore: criteria for validation summaries, especially when the validation is not fully enforced by a guard or the work item needs an explicit closure checklist item.

Common Mistakes