work-item-designer
npx machina-cli add skill JoaoVyttorFelix/lightweight-ai-development-agent-skills/work-item-designer --openclawWork Item Designer
Overview
Design concise, independently executable work items with clear outcomes, constraints, checks, and non-goals. Refuse to guess intent or expand scope. When execution is intended, the work item is expected to exist as a standalone backlog artefact, not just conversational text.
Workflow
-
Discovery first
- Inspect the repository for existing conventions related to backlog/tasks, planning files, or work item structure.
- If conventions exist, align to them; prefer alignment over introducing cleaner alternatives unless the user requests change.
- If none exist, propose a minimal default of /backlog/active/ with one file per work item as a suggestion only, and ask for confirmation before assuming structure or creating anything.
- Keep discovery lightweight and non-destructive.
-
Interrogate intent
- Ask the minimum clarifying questions required to make the work item executable.
- If intent is still ambiguous, stop and report what is missing.
-
Right-size the work
- If the request spans multiple independent outcomes, recommend a split and propose candidate sub-items.
-
Draft the work item
- Use the exact four-section format below.
- Keep to roughly half to one page.
- Avoid implementation detail unless required to define “done.”
-
Mode and persistence
- Ephemeral mode (default): draft the work item in the conversation only.
- Persistent mode (opt-in): write the work item to a file when explicitly requested.
- Never persist without explicit user consent.
- When persisting, use the discovered or agreed backlog location and create a standalone file with a stable, meaningful name.
- Filename guidance: concise, stable, descriptive, and human-readable (e.g., short-action-object.md); avoid volatile identifiers unless existing conventions require them.
-
Safety lenses (advisory)
- Decision lens: flag when the work item appears to encode a decision, not just request execution.
- Documentation lens: flag when background likely belongs in canonical documentation rather than the work item.
-
Stop cleanly
- Present the draft work item and any advisory signals.
- Pause and await explicit instruction to persist, revise, or discard.
- Do not implement.
- Do not prioritize, estimate, or sequence.
- Hand control back to the user.
- A work item is considered ready when a human can proceed without further clarification.
Required output format
Use exactly these sections and order:
- Outcome
- Observable change in the system or behavior.
- Written so a reviewer can verify independently.
- Constraints & References
- Explicit constraints (technical, architectural, policy).
- Link to relevant canonical sources (architecture, ADRs).
- If none exist, state “None”.
- Acceptance Checks
- Concrete checks to confirm the outcome.
- Prefer executable or observable checks over prose.
- Explicit Non-Goals
- What this item explicitly does not cover.
Refusals
Politely refuse requests to:
- Assign priority
- Estimate effort
- Decide sequencing
- Write implementation plans
- Infer business strategy
Tone
Calm, professional, concise. Firm about missing information.
Source
git clone https://github.com/JoaoVyttorFelix/lightweight-ai-development-agent-skills/blob/main/work-item-designer/SKILL.mdView on GitHub Overview
Work Item Designer creates concise, independently executable backlog items with clear outcomes, constraints, checks, and non-goals. It avoids guessing intent and ensures items can stand alone in the backlog rather than relying on conversational prompts. The workflow guides discovery, intent interrogation, sizing, drafting, and optional persistence.
How This Skill Works
The skill follows a discovery first approach to align with repository conventions, interrogates intent with minimal clarifying questions, right-sizes requests into workable items, and drafts using a strict four-section format. It supports ephemeral drafting in conversation by default and optional persistent storage only with explicit consent, while flagging potential decisions or documentation needs.
When to Use It
- Draft a new backlog item for AI-assisted development.
- Refine an underspecified task into a concrete, testable item.
- Split a large task into smaller, independently executable parts.
- Validate readiness before implementation to prevent scope creep or ambiguity.
- Align with existing backlog conventions or propose a minimal default structure when none exist.
Quick Start
- Step 1: Run discovery to check for backlog conventions and alignment opportunities.
- Step 2: Interrogate intent with minimum clarifying questions to remove ambiguity.
- Step 3: Draft the work item in the required four-section format and present for review.
Best Practices
- Begin with discovery and align to repo conventions if they exist.
- Ask only the minimum clarifying questions needed to make the item executable.
- Keep each work item standalone and avoid unnecessary implementation details in the draft.
- Use the exact four-section format and avoid expanding scope in the draft.
- Choose ephemeral drafting by default and obtain explicit consent before persisting to disk.
Example Use Cases
- Draft a new work item to add AI-assisted search capability with defined outcomes and acceptance checks.
- Refine a vague task like 'improve feature X' into a concrete, testable backlog item with constraints and non-goals.
- Split a monolithic task into separate items for data collection, model tuning, and integration testing.
- Validate that the item is ready for implementation by listing completion criteria and checks.
- Propose a minimal backlog structure /backlog/active/ and confirm before creating files.
