complexity-analysis

Principle

Focus on the unknowns, not the knowns. Unknown work dominates software projects.

Evidence Rule

Every classification (known/unknown) must cite the evidence that supports it. Reference code, ADR, spec, or absence thereof. If uncertain, say so and indicate what information would resolve the uncertainty.

Analysis Structure

1. Known Work

Tasks whose effort can be estimated with confidence:

• We have done something similar in this project
• Established pattern in ADR or existing code
• Well-defined scope in the spec
• Existing test coverage in the affected area
• Localized change (few impacted dependencies)

For each item, indicate why it is known (e.g., "CRUD endpoint, same pattern as src/api/users").

2. Unknown Work (Risks)

Signals of uncertainty:

• First time (new technology, integration, or pattern)
• External dependency (third-party API, another team's service)
• Vague requirement ("must be fast", "easy to use")
• Pending decision (no ADR exists for technical choice)
• Legacy code (area without tests or documentation)
• Concurrency/scale (behavior under load not tested)
• Cross-team coordination without agreed interface

For each risk, indicate: what the risk is, why it is a risk, and impact if it materializes.

3. Dependencies

Flag tentative dependencies, without commitment, or without agreed timeline.

4. Open Questions

Before proposing scenarios, list decisions or information that need a human response:

• Decisions needed before starting
• Pending requirement clarifications
• Access or approvals not granted

5. Scenarios (2-3 approaches)

6. Recommendation

Indicate the recommended scenario with explicit justification ("recommended because..."), linking to evidence and identified risks.

For high risks, suggest a spike or timebox to reduce uncertainty before committing.

Risk Classification

Format for Work Items

In the User Story body (GitHub/Azure DevOps):

## Complexity Analysis

**Risk:** [High/Medium/Low]

### Known Work
- Item 1 (estimate)
- Item 2 (estimate)

### Identified Risks
- Risk 1: [description and potential impact]
- Risk 2: [description and potential impact]

### Scenarios
| Scenario | Base effort | If risks materialize | Recommended? |
|----------|-------------|----------------------|--------------|
| A | X days | Y days | |
| B | X days | Y days | yes |

### Decision
[Chosen scenario and justification, or "Awaiting team decision"]

When to Revisit Analysis

The analysis should be updated when:

• A risk materializes (document actual impact)
• A new risk is discovered during implementation
• The scenario decision is changed
• A relevant ADR is created or modified

Anti-patterns

• Do not give a number without justification (e.g., "3 story points")
• Do not ignore risks to appear faster
• Do not list only known work
• Do not present a single scenario as "the solution"
• Do not hide assumptions: always make them explicit
• Do not claim confidence you do not have: declare the uncertainty