kaddo-kdd/kaddo/work-item-refinement

Work Item Refinement Skill

Purpose

Standardize how a Work Item is sharpened from a rough idea into a ready, implementable item.

When to use

When improving a draft Work Item, or turning a backlog idea / roadmap candidate into a ready item.

Inputs

The context pack and the Work Item (draft or candidate).

Output

An improved Work Item with: actor and outcome, current behavior, target behavior, entry points, end-to-end flow, impact analysis, module coverage, scope unknowns, scope confidence, problem, expected result, scope, out of scope, acceptance criteria (including end-to-end criteria for user-facing changes), validation (how to test it), definition of done, open questions and dependencies.

Steps

1. Outcome framing — identify actor, current behavior, target behavior, observable completion.
2. Journey reconstruction — map entry point, interaction, service/API, state change, response,

final outcome.

1. Surface review — evaluate: product/UI, frontend, backend, database, configuration, feature

flags, content/copy, authentication/authorization, notifications, analytics, documentation, operations/release — as affected, reviewed-not-affected, unknown, or not-applicable.

1. Module review — for multirepo, evaluate each mapped module with the same statuses.
2. Resource review — ask: does this change need to observe, modify, validate or deliver against a

known external resource of the project (a Project Resource under knowledge/tech/resources/ — database, cloud, API, queue, storage…)? If so, declare it in the WI front matter resources: with a role (affected, implementation, validation, delivery). Resources are external systems, distinct from affected_modules (code). Not every WI needs resources (e.g. a CSS change does not).

1. Completeness review — confirm: outcome covered, journey covered, modules assessed, resources

assessed, unknowns visible, acceptance criteria end-to-end, scope and out-of-scope coherent.

Rules

• Do not implement code.
• Do not expand scope without explicit confirmation.
• Do not create mega Work Items — split when it covers multiple outcomes.
• Keep acceptance criteria testable.
• Include at least one end-to-end acceptance criterion for user-facing changes.
• Do not reduce a product intent to the first technical implementation found.
• Evaluate surfaces and modules before proposing files.
• Consider Project Resources when the scope justifies it; never invent resources not backed by

project knowledge, and keep resources (external systems) separate from affected_modules (code).

• This skill refines scope and acceptance criteria but does not approve implementation readiness.

Readiness requires human confirmation through kaddo ready or the MCP mark_work_item_ready action.

Quality checklist

• Actor and outcome are identified.
• Current and target behavior are documented.
• Journey is reconstructed for user-facing changes.
• Surfaces and modules are evaluated with explicit statuses.
• Problem and expected result are unambiguous.
• Scope and out-of-scope are explicit.
• Acceptance criteria include end-to-end validation when applicable.
• Scope unknowns are visible, not hidden.
• Scope confidence is declared with reasons.
• Open questions and dependencies are surfaced, not hidden.

Example output

A Work Item markdown with the sections above filled in, ready for the implementation-agent.