Work Item Patterns
Work Item Patterns
When to Use This Skill
Use this skill when implementing work item patterns patterns in your codebase.
How to Use This Skill
- Review the patterns and examples below
- Apply the relevant patterns to your implementation
- Follow the best practices outlined in this skill
Level 1: Quick Reference (Under 500 tokens)
Work Item Hierarchy
Epic (large initiative)
├── Feature (user-facing capability)
│ ├── Story (user value unit)
│ │ ├── Task (implementation work)
│ │ └── Task
│ └── Story
└── Feature
GitHub Issue Template
# .github/ISSUE_TEMPLATE/feature.yml
name: Feature Request
description: Suggest a new feature
body:
- type: textarea
id: description
attributes:
label: Description
description: Describe the feature
validations:
required: true
- type: textarea
id: acceptance
attributes:
label: Acceptance Criteria
value: |
- [ ] Criterion 1
- [ ] Criterion 2
Level 2: Implementation Details (Under 2000 tokens)
Sprint Planning Structure
## Sprint 2024-W01 (Jan 1-7)
### Goals
- [ ] Complete user authentication
- [ ] Deploy to staging
### Capacity
- Team: 40 points
- Planned: 38 points
### Work Items
| ID | Title | Points | Assignee | Status |
|----|-------|--------|----------|--------|
| #123 | Login flow | 8 | @dev1 | In Progress |
| #124 | Password reset | 5 | @dev2 | Todo |
Work Breakdown Structure
interface WorkItem {
id: string;
title: string;
type: 'epic' | 'feature' | 'story' | 'task';
status: 'todo' | 'in_progress' | 'review' | 'done';
points?: number;
parentId?: string;
children?: WorkItem[];
}
function calculateProgress(item: WorkItem): number {
if (!item.children?.length) {
return item.status === 'done' ? 100 : 0;
}
const childProgress = item.children.map(calculateProgress);
return childProgress.reduce((a, b) => a + b, 0) / childProgress.length;
}
Level 3: Complete Reference (Full tokens)
Automated Status Tracking
async function syncGitHubIssues(repo: string) {
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data: issues } = await octokit.issues.listForRepo({
owner: repo.split('/')[0],
repo: repo.split('/')[1],
state: 'all',
labels: 'sprint-current',
});
return issues.map(issue => ({
id: issue.number.toString(),
title: issue.title,
status: issue.state === 'closed' ? 'done' :
issue.labels.some(l => l.name === 'in-progress') ? 'in_progress' : 'todo',
assignee: issue.assignee?.login,
}));
}
Best Practices:
- Keep work items small (1-3 days max)
- Link commits to work items
- Update status in real-time
- Use labels for categorization
- Review velocity regularly
Success Output
When successful, this skill MUST output:
✅ SKILL COMPLETE: work-item-patterns
Completed:
- [x] Work item hierarchy established (epic → feature → story → task)
- [x] GitHub issue templates created and tested
- [x] Sprint planning structure implemented
- [x] Automated status tracking configured
- [x] Work breakdown structure defined
- [x] Progress tracking functional
Outputs:
- .github/ISSUE_TEMPLATE/*.yml (issue templates)
- Sprint planning document/board
- Work item tracking dashboard
- Velocity metrics and reports
- Integration with git commits
Verification:
- Issues created follow templates
- Sprint board reflects current work
- Status updates sync automatically
- Velocity trends visible
Completion Checklist
Before marking this skill as complete, verify:
- Work item hierarchy defined (epic/feature/story/task)
- GitHub issue templates created in .github/ISSUE_TEMPLATE/
- Sprint planning structure documented
- Work items sized appropriately (1-3 days)
- Acceptance criteria defined for all stories
- Status tracking automated (GitHub Actions or bot)
- Velocity metrics tracked over 3+ sprints
- Team trained on work item creation process
- Labels/tags established for categorization
- Integration with git commits configured
Failure Indicators
This skill has FAILED if:
- ❌ Work items too large (>5 days effort)
- ❌ No clear hierarchy or relationships
- ❌ Acceptance criteria missing or vague
- ❌ Status updates manual and frequently stale
- ❌ No velocity tracking or metrics
- ❌ Team confusion about work item types
- ❌ Issue templates not being used
- ❌ Sprint planning chaotic or inconsistent
- ❌ No link between commits and work items
When NOT to Use
Do NOT use this skill when:
- Solo projects with no team coordination (use simple TODO list)
- Research/exploration work (outcome unpredictable)
- Emergency hotfixes (bypass formal planning)
- Proof-of-concept phase (premature process)
- Team already has established system (don't force change)
- Alternative: Use lightweight Kanban for simple workflows
Use alternative approaches for:
- Personal productivity → TODO.md or simple task list
- Research spikes → Time-boxed experiments with goals
- Bug tracking → Dedicated bug tracker with severity
- Customer support → Ticket system (Zendesk, etc.)
Anti-Patterns (Avoid)
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Waterfall epics (months-long) | No feedback, high risk | Break into 2-week increments |
| Vague acceptance criteria | No clear definition of done | Use Given/When/Then format |
| Status never updated | Stale information, false confidence | Automate status sync with git/CI |
| No story points | Cannot track velocity | Estimate all work items |
| Bottom-up only planning | No strategic alignment | Start with epics, decompose |
| Too many work item types | Confusion, overhead | Stick to 3-4 levels max |
| Work items for every commit | Bureaucratic overhead | Bundle related changes |
| No retrospective on velocity | Cannot improve estimation | Review and adjust every sprint |
Principles
This skill embodies these CODITECT principles:
- #6 Clear, Understandable, Explainable - Work items define scope clearly
- #5 Eliminate Ambiguity - Acceptance criteria remove interpretation
- #10 Iterative Refinement - Sprint-based incremental delivery
- Transparency - Visible progress and blockers
- Team Alignment - Shared understanding of work
- Data-Driven - Velocity metrics inform planning
Related Standards: