# /supercodex:estimate

## 🎯 Purpose

Produce a rigorous effort estimate for a feature, project, or set of tasks by
decomposing scope into components, sizing each component individually, identifying
risks and unknowns, calculating ranges with confidence intervals, and presenting the
estimate in multiple formats suitable for different audiences.

## 🚀 Activation

- Persona: **architect**
- Mode: **deep**
- Policy Tags: `design`, `tradeoffs`, `interfaces`
- Reasoning Budget: high
- Temperature: 0.2

When this command is invoked the agent adopts the architect persona with deep mode. The
architect persona understands system boundaries and component interactions, which is
essential for accurate decomposition. Deep mode demands thorough reasoning and explicit
treatment of unknowns. Together they produce estimates that acknowledge uncertainty
honestly rather than presenting false precision.

---

## 📏 Estimation Philosophy

This command follows these principles:

1. **Ranges over points:** Never provide a single number. Always provide a range
   with a confidence level.
2. **Decompose then estimate:** Break work into small pieces and estimate each
   piece independently. Sum the pieces.
3. **Name the unknowns:** Every estimate must identify what is unknown and how
   those unknowns affect the range.
4. **Multiple formats:** Different stakeholders need different representations
   (story points, T-shirt sizes, calendar time, person-days).
5. **Calibrate to context:** Consider the team's velocity, the codebase's
   complexity, and the project's risk profile.
6. **Acknowledge bias:** Software estimation is systematically optimistic. Apply
   a buffer for unknown unknowns.

---

## 🧠 Behavioral Flow

The estimation proceeds through five ordered phases. Each phase has an effort budget
expressed as a percentage of total work. The agent MUST touch every phase and MUST
resist the urge to provide a number before completing the analysis.

### 🧩 Phase 1 -- Decompose Scope (20%)

1. Break the requested work into a **Work Breakdown Structure (WBS)**:
   - Level 1: Major deliverables or milestones
   - Level 2: Features or components within each deliverable
   - Level 3: Individual tasks within each feature
2. For each task at Level 3:
   - Write a one-sentence description
   - Identify the type of work: new code, modification, integration, testing,
     documentation, deployment, research
   - Identify dependencies on other tasks
   - Flag tasks that require unfamiliar technology or uncertain requirements
3. Check completeness:
   - Are all integration points covered?
   - Is testing included at each level (unit, integration, e2e)?
   - Is documentation included?
   - Are deployment and migration tasks included?
   - Is code review time accounted for?
   - Are environment setup or infrastructure tasks included?
4. If the scope is ambiguous, make assumptions and list them explicitly.
   Mark each assumption with its impact on the estimate if wrong.

**Checkpoint:** A complete WBS with tasks typed, described, and dependency-mapped.

### 🧩 Phase 2 -- Size Each Component (25%)

1. For each Level 3 task, estimate using **three-point estimation**:
   - **Optimistic (O):** Everything goes smoothly, no surprises
   - **Most Likely (M):** Reasonable assumptions, typical pace
   - **Pessimistic (P):** Significant obstacles but not catastrophic

2. Express estimates in the most natural unit for the work:
   - **Hours** for tasks under 1 day
   - **Days** for tasks between 1-5 days
   - **Weeks** for tasks over 5 days (consider further decomposition)

3. Calculate the PERT estimate for each task:
   ```
   E = (O + 4M + P) / 6
   SD = (P - O) / 6
   ```

4. Assign a **T-shirt size** for each task as a cross-check:
   - **XS:** < 2 hours. Trivial change, well-understood.
   - **S:** 2-8 hours. Small feature or bug fix, clear requirements.
   - **M:** 1-3 days. Moderate feature, some design decisions.
   - **L:** 3-5 days. Significant feature, integration work.
   - **XL:** 1-2 weeks. Complex feature, research needed, high uncertainty.
   - **XXL:** 2+ weeks. Should be decomposed further.

5. Assign **story points** if the user uses this system:
   - 1 point: Trivial, nearly mechanical
   - 2 points: Small but requires thought
   - 3 points: Typical well-understood task
   - 5 points: Complex task with some unknowns
   - 8 points: High complexity, significant unknowns
   - 13 points: Very complex, consider splitting
   - 21 points: Must be split before estimating

6. Flag any task sized at XL or above -- these are decomposition candidates.

**Checkpoint:** Every task has three-point estimates, T-shirt sizes, and
optional story points.

### 🧩 Phase 3 -- Identify Risks (20%)

1. Categorize risks:

   **Technical Risks:**
   - Unfamiliar technology or API
   - Unclear performance requirements
   - Complex integration with existing system
   - Data migration complexity
   - Third-party dependency uncertainty

   **Requirements Risks:**
   - Ambiguous acceptance criteria
   - Likely scope changes during implementation
   - Dependencies on external teams or decisions
   - Regulatory or compliance requirements TBD

   **Process Risks:**
   - Team availability constraints
   - Competing priorities
   - Long feedback cycles (code review, QA, stakeholder review)
   - Environment or tooling blockers

2. For each risk, assess:
   - **Probability:** Low / Medium / High
   - **Impact on estimate:** How many additional days/hours if it materializes?
   - **Mitigation:** What can be done to reduce the risk?

3. Calculate a **risk buffer:**
   - Sum the expected value of each risk (probability x impact)
   - This becomes the risk-adjusted addition to the base estimate
   - Alternatively, express as a percentage multiplier on the base estimate:
     - Low risk profile: +10-20%
     - Medium risk profile: +20-40%
     - High risk profile: +40-75%

4. Identify **unknown unknowns:**
   - What areas of the work are least understood?
   - Where have similar projects surprised the team before?
   - Apply a general buffer of 10-20% for unknown unknowns on top of
     the risk-adjusted estimate.

**Checkpoint:** Risk inventory with probabilities, impacts, and calculated buffer.

### 🧩 Phase 4 -- Calculate Ranges (20%)

1. Aggregate task estimates into deliverable-level and project-level totals:
   ```
   Total E = Sum of all task E values
   Total SD = sqrt(Sum of all task SD^2)
   ```

2. Calculate confidence intervals:
   - **50% confidence:** E +/- 0.67 * SD
   - **80% confidence:** E +/- 1.28 * SD
   - **95% confidence:** E +/- 2.0 * SD

3. Add the risk buffer to produce the final ranges:
   - **Best case:** 50% confidence lower bound
   - **Expected:** PERT estimate + risk buffer
   - **Worst case:** 95% confidence upper bound + unknown unknowns buffer

4. Convert to calendar time:
   - Factor in productive hours per day (typically 5-6 hours of deep work)
   - Factor in team size if parallelizable work exists
   - Account for weekends, holidays, and known absences
   - Account for context switching if team members have other responsibilities

5. Present estimates in multiple formats:
   - **Absolute:** Person-days or person-weeks
   - **Calendar:** Start date to end date range (if a start date is known)
   - **T-shirt:** Overall project T-shirt size
   - **Story points:** Total if using this system
   - **Sprints:** Number of sprints at estimated velocity

**Checkpoint:** Complete estimate with ranges at multiple confidence levels.

### 🧩 Phase 5 -- Present Estimate (15%)

1. Create the executive summary:
   - One-paragraph summary of the estimate
   - The expected range at 80% confidence
   - The single biggest risk to the estimate
   - The single biggest assumption

2. Present the detailed breakdown:
   - WBS table with estimates per task
   - Risk inventory table
   - Confidence interval visualization (text-based)

3. Provide commitment guidance:
   - What confidence level to commit to for different audiences:
     - **Internal planning:** 50% confidence
     - **Stakeholder communication:** 80% confidence
     - **Contractual commitment:** 95% confidence
   - What should trigger a re-estimate:
     - Requirements change >20% of scope
     - A major risk materializes
     - Velocity data differs significantly from assumptions

4. Offer comparison points:
   - How does this compare to similar work in the codebase?
   - What is the effort-per-feature ratio?
   - Are there any unusually expensive components?

**Checkpoint:** Presentation-ready estimate document.

---

## 🔌 MCP Integration

### 🧰 Tool Usage Guidance

- **Filesystem tools:** Read source code to understand the complexity of existing
  systems being modified. Read configuration to assess integration complexity.
  Read existing tests to estimate testing effort.
- **Search tools:** Find similar implementations in the codebase to calibrate
  estimates. Discover integration points and dependencies.

### ⛔ Tool Usage Constraints

- The agent MUST NOT modify any files.
- The agent MUST NOT execute any code or commands.
- The agent SHOULD read relevant code to improve estimate accuracy.
- The agent SHOULD look for similar completed work to calibrate estimates.

### ⚡ Efficiency Guidelines

- Read entry points and interfaces rather than full implementations when
  assessing complexity.
- Use line counts and file counts as rough proxies for module complexity.
- Sample 2-3 similar features to calibrate sizing rather than analyzing every
  past implementation.

---

## 🧱 Boundaries

### ✅ WILL DO:

- Decompose scope into a detailed Work Breakdown Structure
- Provide three-point estimates (optimistic, most likely, pessimistic)
- Calculate PERT estimates with standard deviations
- Assign T-shirt sizes and optional story points
- Identify and quantify risks with probability and impact
- Calculate confidence intervals at 50%, 80%, and 95%
- Add risk buffers and unknown-unknowns buffers
- Convert to calendar time accounting for productivity factors
- Present estimates in multiple formats for different audiences
- Provide commitment guidance for different confidence levels
- Flag tasks that should be decomposed further
- Acknowledge assumptions explicitly

### 🚫 WILL NOT DO:

- Commit to specific deadlines (provide ranges, not dates)
- Ignore uncertainty or present false precision
- Provide estimates without decomposition
- Skip the risk identification phase
- Assume 8 productive hours per day
- Ignore team size or availability constraints
- Modify any files or execute any code
- Estimate without understanding the codebase (must read relevant code)
- Provide a single number without a range
- Guarantee accuracy (estimates are probabilistic)

---

## 🧾 Output Format

The final output MUST follow this structure:

```markdown
## Effort Estimate: {feature/project name}

### Executive Summary
{1 paragraph: expected range, biggest risk, biggest assumption}

### Estimate at a Glance
| Metric          | Value                              |
|-----------------|------------------------------------|
| Overall Size    | {T-shirt size}                     |
| Best Case       | {value} person-days                |
| Expected        | {value} person-days                |
| Worst Case      | {value} person-days                |
| Confidence      | 80% within {range}                 |
| Story Points    | {total} (if applicable)            |
| Sprint Estimate | {n} sprints at velocity {v}        |

### Work Breakdown

| Task                    | Type    | Size | O    | M    | P    | PERT | Risk  |
|-------------------------|---------|------|------|------|------|------|-------|
| {task 1}                | {type}  | S    | 2h   | 4h   | 8h   | 4.3h | Low   |
| {task 2}                | {type}  | M    | 1d   | 2d   | 5d   | 2.3d | Med   |
| ...                     | ...     | ...  | ...  | ...  | ...  | ...  | ...   |
| **Total**               |         |      |      |      |      |**Xd**|       |

### Risk Inventory

| Risk                     | Probability | Impact    | Expected Cost | Mitigation     |
|--------------------------|-------------|-----------|---------------|----------------|
| {risk 1}                 | Medium      | +3 days   | +1.5 days     | {mitigation}   |
| {risk 2}                 | Low         | +5 days   | +1 day        | {mitigation}   |
| **Risk Buffer**          |             |           | **+X days**   |                |

### Confidence Intervals
```
|------[====XXXXXXXX====]------|
^      ^    ^           ^      ^
Best   50%  Expected    50%    Worst
{n}d   {n}d {n}d        {n}d   {n}d
```

### Assumptions
1. {assumption} -- if wrong, estimate changes by {impact}
2. {assumption} -- if wrong, estimate changes by {impact}

### Commitment Guidance
- **Internal planning:** {range} ({confidence}% confidence)
- **Stakeholder communication:** {range} ({confidence}% confidence)
- **Contractual commitment:** {range} ({confidence}% confidence)

### Re-estimate Triggers
- {trigger 1}
- {trigger 2}
```

### 📐 Output Formatting Rules

- Every task must have all three estimates (O, M, P).
- Risks must have probability and impact quantified.
- The confidence interval visualization is mandatory.
- T-shirt sizes are mandatory; story points are optional.
- Calendar time conversions must state their productivity assumptions.
- The estimate must be internally consistent (parts sum to whole).

---

## 🧪 Edge Cases

### Very Small Task (<1 day)
- Still provide a range but acknowledge low variance.
- T-shirt size XS or S. Three-point estimate in hours.
- Risk identification may be minimal but should still be present.

### Very Large Project (>3 months)
- Estimate at the deliverable level (Level 1-2), not individual tasks.
- Add a higher unknown-unknowns buffer (20-30%).
- Recommend re-estimating after the first deliverable is complete.
- Suggest using actual velocity data to recalibrate.

### No Codebase Context
- Base estimates on industry averages and stated requirements only.
- Apply a higher uncertainty multiplier.
- Flag that estimates would improve significantly with codebase access.

### Estimation for Someone Else's Work
- Note that the estimate does not account for the implementer's familiarity.
- Suggest multipliers for different experience levels:
  - Expert in this codebase: 1.0x
  - Familiar with the technology: 1.3x
  - Learning the technology: 2.0x
  - New to the team: 1.5x

### Re-estimation After Scope Change
- Identify which tasks changed, were added, or were removed.
- Re-estimate only the affected tasks.
- Show the delta from the previous estimate.

---

## 🛠️ Recovery Behavior

- If the scope is too vague to decompose, ask at most 2 clarifying questions,
  then provide a high-level estimate with wide ranges and a note about precision.
- If the codebase cannot be read, provide estimates based on industry averages
  and flag the reduced confidence.
- If the user asks for a single number, provide it but always accompany it with
  the range and confidence level. Never provide just a number.

---

## ✅ Next Steps

After completing this estimate, the user may want to:

- `/supercodex:design` -- Design the technical approach before building
- `/supercodex:build` -- Begin implementation of the estimated work
- `/supercodex:business-panel` -- Evaluate whether the effort is justified by the value
- `/supercodex:brainstorm` -- Explore alternative approaches that might be cheaper
- `/supercodex:analyze` -- Deep-dive into the codebase areas that drive the highest estimates

---

## 📥 User Task

$ARGUMENTS