complexity-estimation
verified93ed1535-6a58-4761-9836-8af8ae947094
Estimate task size and flag unknowns before committing to a plan — T-shirt sizing, dependency mapping, and surfacing the riskiest unknown. Use when asked "how long will this take."
Metadata
Skill file
# Complexity Estimation
Use when asked "how long will this take", "is this feasible", or "what's the
risk level." Good estimation is not about accuracy — it is about surfacing
**unknowns** and communicating **confidence**, not committing to a date.
## 1. T-shirt sizing rubric
Size tasks with S/M/L/XL using concrete heuristics, not gut feel. Read the code
first — never estimate a codebase you have not opened.
| Size | Heuristic | Approximate effort |
|---|---|---|
| **S** | One file, one function, zero unknowns, no integration. | < 4 hours |
| **M** | 2–4 files, known pattern, existing test coverage, local change. | 1–2 days |
| **L** | 5+ files, new module or integration, at least one unknown, new test suite. | 3–5 days |
| **XL** | Multiple modules, new data model, many unknowns or integrations, needs a spike first. | 1–2 weeks + spikes |
If you cannot decide between two sizes, **pick the larger one** and note why.
## 2. Unknown-triangulation
List the **top 3 unknowns** that could blow up the estimate. For each, assign a
mitigation:
| Unknown | Mitigation | Effort |
|---|---|---|
| Does library X handle Unicode edge cases? | Write a 30-min spike | Low |
| What is the prod DB schema for the affected tables? | Read the migration files + ask DBA | Low |
| Will the new endpoint stay under the latency budget? | Load-test prototype before merging | Medium |
A task with zero unknowns is S. A task with 3+ unknowns is at least L, no matter
how small it looks.
## 3. The 3x rule for unknown-heavy work
If the task has significant unknowns (no spike done yet, no prototype), multiply
your initial estimate by **3x**. This is not pessimism — it is the empirically
observed penalty of learning during implementation.
```
estimate = (known_effort × 1.0) + (unknown_effort × 3.0)
```
Known effort: things you have done before, with libraries you understand, in code
you know. Unknown effort: anything involving a new library, a new API, a new data
model, or a part of the codebase you have never touched.
## 4. Estimation table (the deliverable)
Write an estimation table, not a single number. A single number implies confidence
you do not have.
```markdown
## Estimate: user deletion endpoint
| Component | Size | Known? | Risk |
|---|---|---|---|
| Endpoint + validation | M | Yes — similar to existing routes | Low |
| Cascade-delete logic | M | Partial — FK graph is undocumented | Medium |
| Audit log table + migration | S | Yes — standard Alembic workflow | Low |
| Integration tests with Testcontainers | M | No — first use of Testcontainers in this repo | High |
| Documentation + changelog | S | Yes | Low |
| **Total** | **L** | | |
| **Confidence** | **Medium** | Two unknowns; spike Testcontainers first. | |
```
## 5. What not to estimate
- Do not estimate in hours/days for anything L or XL. Use t-shirt sizes until the
unknowns are resolved, then re-estimate in hours if needed.
- Do not estimate on behalf of other people. "Bob can do it in a day" is fiction.
- Do not omit integration and merge work. Integration is often 30–50% of total
effort and the most underestimated line item.
## 6. Estimation for bug fixes vs features
Bug fixes and features are estimated differently — do not use the same rubric.
| | Bug fix | Feature |
|---|---|---|
| Dominant unknown | "Where is the cause?" | "What is the design?" |
| Estimate anchor | Time to reproduce + isolate, not to write the fix | Time to design + build + integrate |
| Typical range | S (known cause) to M (unknown cause) | S to XL |
| Best de-risking move | Reproduce first, then estimate | Spike the riskiest unknown |
For a bug, "the fix is one line" is only true *after* you have found the line.
Estimate the search, not just the edit.
## 7. Re-estimating mid-task
Estimates rot. Re-estimate when:
1. A spike/exploration resolves an unknown (usually *down*).
2. You hit an unlisted unknown (usually *up*).
3. Scope changes (requirements, integrations added/removed).
When re-estimating, **announce it** rather than silently sliding the date. A
revision with a reason ("the Testcontainers spike found 3 extra migration steps")
builds trust; a silent slip destroys it.
## Guardrails
- Do **not** estimate without reading the relevant code first. A blind estimate is a lie.
- Do **not** give a single number without a confidence level.
- Do **not** call something S if it has unknowns. Unknowns → at least L.
- Do **not** ignore integration, testing, documentation, and deployment in the estimate.
- If asked for a date and you have unknowns, answer with "after we spike X, I can
give a date."
## Pitfalls
- **Estimating without reading code** — the most common and damaging error. A
task you have not looked at is always underestimated by 2x–10x.
- **Confidence without evidence** — "I'm pretty sure" is not evidence; cite a
prior similar task or a spike result.
- **Ignoring dependency/integration work** — "just call the payment API" is one
line of code and two weeks of reading docs, sandbox setup, and error handling.
- **Over-committing** — stating a single date with high confidence on an L/XL task
that has not been spiked.
- **The planning fallacy** — your estimate is based on the task going smoothly; add
the 3x multiplier for unknowns to correct for it.
## Verify / Checklist
- [ ] The relevant code has been read before the estimate was produced.
- [ ] Size is given as S/M/L/XL with concrete heuristics per size.
- [ ] Top 3 unknowns are listed with mitigations.
- [ ] The 3x rule was applied to any unknown-heavy components.
- [ ] The estimate includes integration, testing, docs, and deployment.
- [ ] A confidence level is stated (high/medium/low) with reasoning.
- [ ] For L/XL tasks, spikes are scheduled before a date commitment.Attached files
No attached files.