Skip to content

Commit fbd6ce0

Browse files
breadonceebreadoncee
authored
feat(skills): add P0 backbone skills for product development lifecycle
Add 9 foundational backbone skills and the skills-index.yaml registry covering the core product development lifecycle phases: ideation, planning, implementation, testing, deployment, and iteration.
1 parent 9ac4e40 commit fbd6ce0

10 files changed

Lines changed: 1604 additions & 0 deletions

File tree

‎skills/create-adr/SKILL.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
name: create-adr
3+
description: Create an Architecture Decision Record when the user asks to document a technical decision, record an architecture choice, create an ADR, or explain why a particular approach was chosen
4+
owner: chalk
5+
version: "1.0.0"
6+
metadata-version: "1"
7+
allowed-tools: Read, Glob, Write, Grep
8+
argument-hint: "[decision title or question being decided]"
9+
---
10+
11+
# Create Architecture Decision Record
12+
13+
## Overview
14+
15+
Create a structured Architecture Decision Record (ADR) following Michael Nygard's format. ADRs capture the context, decision, alternatives considered, and consequences of significant technical choices so future engineers understand *why* something was decided, not just *what* was decided.
16+
17+
## Workflow
18+
19+
1. **Read project context** -- Read `.chalk/docs/engineering/` for existing architecture docs and conventions. Read any existing ADRs to understand prior decisions and link related records.
20+
21+
2. **Determine the next ADR number** -- List files in `.chalk/docs/engineering/` matching the pattern `*_adr_*.md`. Find the highest number and increment by 1. If no ADRs exist, start at `1`.
22+
23+
3. **Clarify the decision** -- From `$ARGUMENTS` and conversation context, identify:
24+
- The specific technical decision being made (or proposed)
25+
- The forces and constraints driving the decision
26+
- The alternatives that were (or should be) considered
27+
- Ask the user for clarification if the decision scope is ambiguous
28+
29+
4. **Research alternatives** -- If the user hasn't specified alternatives, propose 2-4 reasonable options based on the project context. Every ADR must have at least 2 alternatives considered, including the chosen approach.
30+
31+
5. **Draft the ADR** -- Write the full ADR using the format below. Be concrete and specific. Avoid vague statements like "it depends" or "we'll figure it out later."
32+
33+
6. **Write the file** -- Save to `.chalk/docs/engineering/<n>_adr_<decision_slug>.md`.
34+
35+
7. **Confirm** -- Tell the user the ADR was created with its path, the decision summary, and any related ADRs it links to.
36+
37+
## Filename Convention
38+
39+
```
40+
<number>_adr_<snake_case_decision>.md
41+
```
42+
43+
Examples:
44+
- `3_adr_use_postgres_over_mongodb.md`
45+
- `7_adr_adopt_event_sourcing_for_orders.md`
46+
- `12_adr_migrate_to_monorepo.md`
47+
48+
## ADR Format
49+
50+
```markdown
51+
# ADR-<number>: <Decision Title>
52+
53+
## Status
54+
55+
<Proposed | Accepted | Deprecated | Superseded by [ADR-X](link)>
56+
57+
## Date
58+
59+
<YYYY-MM-DD>
60+
61+
## Context
62+
63+
<Describe the forces at play: technical constraints, business requirements, team capabilities,
64+
timeline pressure, existing system state. Be specific about what problem triggered this decision.
65+
Reference related ADRs if they exist.>
66+
67+
## Decision
68+
69+
<State the decision clearly and concisely. Use active voice: "We will use X" not "X was chosen."
70+
Include enough detail that someone could implement this without further clarification.>
71+
72+
## Alternatives Considered
73+
74+
| Option | Pros | Cons | Why Rejected |
75+
|--------|------|------|--------------|
76+
| <Chosen option> | <pros> | <cons> | **Selected** |
77+
| <Alternative 1> | <pros> | <cons> | <specific reason> |
78+
| <Alternative 2> | <pros> | <cons> | <specific reason> |
79+
80+
## Consequences
81+
82+
### Positive
83+
84+
- <Concrete benefit 1>
85+
- <Concrete benefit 2>
86+
87+
### Negative
88+
89+
- <Concrete tradeoff 1 and how we will mitigate it>
90+
- <Concrete tradeoff 2 and how we will mitigate it>
91+
92+
### Neutral
93+
94+
- <Side effects that are neither good nor bad but worth noting>
95+
96+
## Revisit When
97+
98+
- <Specific trigger condition 1, e.g., "Monthly active users exceed 100k">
99+
- <Specific trigger condition 2, e.g., "The team grows beyond 5 engineers">
100+
- <Specific trigger condition 3, e.g., "Write volume exceeds 10k ops/sec">
101+
```
102+
103+
## Content Guidelines
104+
105+
### Status Values
106+
107+
| Status | When to Use |
108+
|--------|-------------|
109+
| **Proposed** | Decision is open for discussion, not yet committed |
110+
| **Accepted** | Decision has been agreed upon and is in effect |
111+
| **Deprecated** | Decision is no longer relevant (explain why) |
112+
| **Superseded** | Replaced by a newer ADR (link to it) |
113+
114+
### Writing Good Context
115+
116+
The Context section is the most important part of an ADR. It should answer:
117+
- What problem are we solving?
118+
- What constraints exist (technical, business, timeline)?
119+
- What is the current state of the system?
120+
- Who are the stakeholders affected?
121+
122+
A reader 6 months from now should understand the full picture from Context alone.
123+
124+
### Writing Good Alternatives
125+
126+
For each alternative, the "Why Rejected" column must be specific and honest:
127+
- Good: "Query performance degrades below acceptable thresholds at our projected data volume (>50M rows)"
128+
- Bad: "Doesn't meet our needs"
129+
- Good: "Requires team expertise in Rust which we don't have and can't hire for in Q1"
130+
- Bad: "Too complex"
131+
132+
### Writing Revisit Triggers
133+
134+
Revisit triggers should be concrete, measurable conditions -- not vague timeframes:
135+
- Good: "If P95 response time exceeds 500ms under normal load"
136+
- Bad: "If performance becomes a problem"
137+
- Good: "When we add a second product line that needs independent deployment"
138+
- Bad: "When things change"
139+
140+
### Retroactive ADRs
141+
142+
If documenting a decision that was already made, acknowledge this in the Context section: "This ADR documents a decision made on <date> during <context>. It is being recorded retroactively to preserve the reasoning." This is legitimate and valuable -- most teams under-document decisions.
143+
144+
## Linking Related ADRs
145+
146+
When writing a new ADR, check for related existing ADRs:
147+
- Decisions in the same domain (e.g., multiple database-related ADRs)
148+
- Decisions this one depends on or is constrained by
149+
- Decisions this one supersedes
150+
151+
Reference them in the Context section: "This decision builds on [ADR-3: Use PostgreSQL](3_adr_use_postgres.md) which established our primary data store."
152+
153+
## Anti-patterns
154+
155+
- **ADR without alternatives**: Every decision has alternatives, even if one is "do nothing." If you can't think of alternatives, you haven't understood the decision space. Always include at least 2 options in the Alternatives table.
156+
- **Missing consequences**: An ADR that only lists positive consequences is marketing, not engineering. Every decision has tradeoffs. Name the negative consequences explicitly and describe mitigation strategies.
157+
- **Vague rejection reasons**: "Doesn't fit our needs" is not a rejection reason. Be specific about which needs, what measurement, what threshold.
158+
- **Not recording what was rejected**: The rejected alternatives are often more valuable than the chosen one. They prevent future engineers from re-evaluating options that were already considered.
159+
- **Writing ADRs after the fact without acknowledging it**: Retroactive ADRs are fine, but pretending a decision was carefully evaluated when it was actually made under pressure is dishonest. Acknowledge the circumstances.
160+
- **Overloading a single ADR**: One ADR per decision. If you're covering multiple decisions, split them into separate ADRs that reference each other.
161+
- **Status that never updates**: If a decision is superseded, update the old ADR's status to point to the new one. Stale statuses erode trust in the ADR system.

‎skills/create-estimation/SKILL.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
name: create-estimation
3+
description: Create a three-point estimation when the user asks to estimate effort, scope a feature, size work, forecast timeline, or plan capacity for a project or feature
4+
owner: chalk
5+
version: "1.0.0"
6+
metadata-version: "1"
7+
allowed-tools: Read, Glob, Write, Grep
8+
argument-hint: "[feature or work item to estimate]"
9+
---
10+
11+
# Create Estimation
12+
13+
## Overview
14+
15+
Create a structured three-point estimation using PERT-weighted averages. Breaks work into concrete tasks, estimates each with optimistic/likely/pessimistic bounds, identifies risk factors, and produces a total range with a recommended commitment point.
16+
17+
## Workflow
18+
19+
1. **Read project context** -- Read `.chalk/docs/` for PRDs, user stories, acceptance criteria, and architecture docs. Understanding scope and integration points is essential before estimating.
20+
21+
2. **Determine the next estimation number** -- List files in `.chalk/docs/engineering/` matching the pattern `*_estimation_*.md`. Find the highest number and increment by 1. If none exist, start at `1`.
22+
23+
3. **Understand the scope** -- From `$ARGUMENTS`, conversation context, and project docs, identify:
24+
- What exactly is being estimated (feature, epic, spike, migration)
25+
- Acceptance criteria or definition of done
26+
- Known integration points with existing systems
27+
- Whether this is greenfield or modification of existing code
28+
- If scope is unclear, ask the user before estimating -- estimation without scope understanding is guessing
29+
30+
4. **Break into tasks** -- Decompose the work into concrete, estimatable tasks. Each task should be:
31+
- Small enough to estimate with reasonable confidence (ideally 0.5-3 days of effort)
32+
- Independent enough to estimate separately
33+
- Inclusive of all work types: implementation, testing, code review, documentation, deployment
34+
35+
5. **Three-point estimate each task** -- For every task, provide:
36+
- **Optimistic (O)**: Best case if everything goes smoothly, no surprises, familiar territory
37+
- **Likely (L)**: Most probable duration given normal conditions, some minor friction
38+
- **Pessimistic (P)**: Worst reasonable case -- unfamiliar code, complex bugs, unclear requirements (not catastrophic, just hard)
39+
40+
6. **Calculate PERT estimate** -- For each task: `Expected = (O + 4L + P) / 6`. Sum all task estimates for the total.
41+
42+
7. **Identify risk factors** -- List specific risks that could push the estimate toward the pessimistic end. Assign each a probability (low/medium/high) and impact in time.
43+
44+
8. **Calculate risk buffer** -- Add a percentage buffer based on cumulative risk:
45+
- Well-understood work, few unknowns: 10-20% buffer
46+
- Some unknowns, moderate integration complexity: 20-40% buffer
47+
- Significant unknowns, new technology, complex integrations: 40-70% buffer
48+
49+
9. **Determine recommended commitment** -- The number the team should commit to externally. This is the PERT total + risk buffer, rounded to a sensible unit (half-days for small work, days for medium, weeks for large).
50+
51+
10. **Write the file** -- Save to `.chalk/docs/engineering/<n>_estimation_<feature_slug>.md`.
52+
53+
11. **Confirm** -- Tell the user the estimation was created with its path, the recommended commitment, and the confidence range.
54+
55+
## Filename Convention
56+
57+
```
58+
<number>_estimation_<snake_case_feature>.md
59+
```
60+
61+
Examples:
62+
- `2_estimation_user_authentication.md`
63+
- `5_estimation_payment_integration.md`
64+
- `9_estimation_migrate_to_v2_api.md`
65+
66+
## Estimation Format
67+
68+
```markdown
69+
# Estimation: <Feature or Work Item Title>
70+
71+
Last updated: <YYYY-MM-DD>
72+
73+
## Scope
74+
75+
<Brief description of what is being estimated. Link to PRD or user story if available.
76+
State any scope boundaries explicitly: "This estimate covers X but not Y.">
77+
78+
## Assumptions
79+
80+
- <Assumption 1, e.g., "API contracts are finalized and won't change">
81+
- <Assumption 2, e.g., "Design mockups are complete before development starts">
82+
- <Assumption 3, e.g., "One engineer working full-time on this">
83+
84+
## Task Breakdown
85+
86+
| # | Task | Optimistic | Likely | Pessimistic | PERT Estimate |
87+
|---|------|-----------|--------|-------------|---------------|
88+
| 1 | <Task description> | <O> | <L> | <P> | <(O+4L+P)/6> |
89+
| 2 | <Task description> | <O> | <L> | <P> | <(O+4L+P)/6> |
90+
| 3 | <Task description> | <O> | <L> | <P> | <(O+4L+P)/6> |
91+
| ... | ... | ... | ... | ... | ... |
92+
| | **Subtotal** | **<sum O>** | **<sum L>** | **<sum P>** | **<sum PERT>** |
93+
94+
All values in **engineer-days** unless otherwise noted (1 engineer-day = 1 person working 1 full day).
95+
96+
## Commonly Forgotten Tasks
97+
98+
The following are included in the breakdown above. If any were intentionally excluded, note why.
99+
100+
- [ ] Unit and integration tests
101+
- [ ] Error handling and edge cases
102+
- [ ] Code review iterations (typically 1-2 rounds)
103+
- [ ] Documentation updates (API docs, README, runbook)
104+
- [ ] Migration scripts or data backfill
105+
- [ ] Deployment and rollout (feature flags, staged rollout)
106+
- [ ] Monitoring and alerting setup
107+
- [ ] Performance testing under realistic load
108+
109+
## Risk Factors
110+
111+
| Risk | Probability | Impact | Mitigation |
112+
|------|------------|--------|------------|
113+
| <Specific risk> | Low / Medium / High | +<N> days | <How to reduce likelihood or impact> |
114+
| <Specific risk> | Low / Medium / High | +<N> days | <How to reduce likelihood or impact> |
115+
116+
## Summary
117+
118+
| Metric | Value |
119+
|--------|-------|
120+
| **Optimistic total** | <sum of all O values> |
121+
| **PERT total** | <sum of all PERT values> |
122+
| **Pessimistic total** | <sum of all P values> |
123+
| **Risk buffer** | <X%> (<rationale>) |
124+
| **Recommended commitment** | **<PERT + buffer, rounded>** |
125+
| **Confidence range** | <Optimistic> to <Pessimistic + buffer> |
126+
127+
## Recommended Commitment
128+
129+
**<N> engineer-days** (<approximately N/5 weeks> for a single engineer)
130+
131+
This is the number to communicate externally. It includes the PERT-weighted estimate plus
132+
a <X%> risk buffer for <brief rationale>.
133+
134+
## Revisit Triggers
135+
136+
- Scope changes that add or remove acceptance criteria
137+
- Discovery of unknown integration complexity during implementation
138+
- Actual velocity tracking shows >20% deviation from estimates after first 30% of work
139+
```
140+
141+
## Content Guidelines
142+
143+
### Estimation Units
144+
145+
Use **engineer-days** as the base unit. This measures effort, not calendar time.
146+
147+
- 1 engineer-day = 1 person working 1 full day
148+
- To convert to calendar time, divide by the number of engineers and add coordination overhead (typically 10-20% per additional engineer)
149+
- For very small tasks (< 0.5 days), use hours but convert to days in the summary
150+
151+
### Calibrating Optimistic vs. Pessimistic
152+
153+
The spread between O and P reveals confidence level:
154+
155+
| O:P Ratio | What It Means |
156+
|-----------|---------------|
157+
| 1:1.5 | Very well understood, done it before |
158+
| 1:2 | Mostly understood, some unknowns |
159+
| 1:3 | Significant unknowns, unfamiliar territory |
160+
| 1:5+ | Too uncertain to estimate -- recommend a spike first |
161+
162+
If any single task has a ratio worse than 1:5, flag it as needing a timeboxed investigation spike before estimation is meaningful.
163+
164+
### Breaking Down Tasks Well
165+
166+
Good task breakdown follows these rules:
167+
- Each task has a clear deliverable (not "work on X" but "implement X endpoint with validation")
168+
- Tasks include the full cost: code + tests + review, not just the coding part
169+
- Integration tasks are explicit, not hidden inside implementation tasks
170+
- "Glue work" is accounted for: config changes, environment setup, CI pipeline updates
171+
172+
### Setting Risk Buffer
173+
174+
The buffer is not padding -- it is a quantified acknowledgment of uncertainty:
175+
176+
| Scenario | Suggested Buffer |
177+
|----------|-----------------|
178+
| Mature codebase, well-defined requirements, experienced team | 10-20% |
179+
| Some new technology, requirements mostly stable | 20-40% |
180+
| New codebase or major refactor, evolving requirements | 40-70% |
181+
| Greenfield with unproven technology and unclear requirements | 70-100% (or recommend a spike) |
182+
183+
### Effort vs. Duration
184+
185+
Always clarify the distinction:
186+
- **Effort**: Total engineer-days of work (what you estimate)
187+
- **Duration**: Calendar time to complete (depends on team size, parallel work, interruptions)
188+
- Two engineers don't halve the duration -- coordination overhead adds 10-20% per person
189+
- Context switching between projects adds 20-30% to effective duration
190+
191+
## Anti-patterns
192+
193+
- **Single-point estimates**: "This will take 5 days" is a guess, not an estimate. Always provide the three-point range. The spread itself is valuable information about uncertainty.
194+
- **Anchoring bias**: The first number mentioned becomes the anchor. Break into tasks first, estimate each independently, then sum. Never start with a total and work backward.
195+
- **Not accounting for integration/testing time**: Implementation is typically 40-60% of total effort. The rest is testing, integration, review, deployment, and documentation. If your estimate only covers coding, it is 40-60% of the real number.
196+
- **Estimating without understanding scope**: If you don't have acceptance criteria or a clear definition of done, you cannot estimate. Push back and get clarity first, or estimate the spike to get clarity.
197+
- **Confusing effort with duration**: 10 engineer-days is not "2 weeks." It is 2 weeks for 1 engineer, but could be 1 week for 2 engineers (plus coordination overhead), or 3 weeks for 1 engineer with context switching.
198+
- **Planning fallacy**: People consistently underestimate by 30-50%. If the team has historical data, calibrate against it. If not, lean toward the pessimistic end for commitments.
199+
- **Precision theater**: Reporting "7.3 engineer-days" implies false precision. Round to the nearest 0.5 for small estimates, nearest whole day for medium, nearest week for large.
200+
- **Estimating in isolation**: If the work integrates with systems owned by other teams, account for coordination time, API negotiations, and blocked-waiting time. Cross-team dependencies are the most common source of estimation misses.

0 commit comments

Comments
 (0)