# Epic 3 Retrospective - Work Unit Validation & Discovery

**Date:** 2026-01-11
**Epic:** 3 - Work Unit Validation & Discovery
**Facilitator:** Bob (Scrum Master)
**Status:** Complete

## Epic Summary

**Goal:** Users can validate their Work Units and browse their collection with confidence

**FRs Covered:** FR6, FR7, FR8

**Delivery Metrics:**
- Stories Completed: 3/3 (100%)
- Total Tests: 511+ (125+ new in this epic)
- Code Quality: mypy --strict, ruff check/format passing
- Model Used: Claude Opus 4.5 (claude-opus-4-5-20251101)

## Stories Delivered

| Story | Title | Status | Key Deliverable |
|-------|-------|--------|-----------------|
| 3-1 | Validate Command & Schema Validation | done | `resume validate` with JSON Schema validation |
| 3-2 | Actionable Validation Feedback | done | Content quality checks, weak verb detection, Rich formatting |
| 3-3 | List Command & Filtering | done | `resume list` with tag/confidence filters, sorting |

## What Went Well

### 1. Content Quality Validation (Story 3-2)
The `--content-quality` and `--content-density` flags go beyond basic schema validation. Detecting weak verbs ("managed", "handled", "helped") and suggesting strong alternatives ("orchestrated", "resolved", "enabled") adds genuine value. The 100-160 character bullet length guidance is research-backed resume best practice.

### 2. Rich Output Enhancement
Using Rich Tree and Panel components for error grouping (Story 3-2) and Rich Table for listing (Story 3-3) provides excellent user experience. File paths are clickable in supported terminals using Rich's file link syntax.

### 3. Multiple Filter Support (Story 3-3)
The `--filter` option accepting multiple values with AND logic (`--filter "tag:python" --filter "confidence:high"`) enables sophisticated queries. Case-insensitive matching reduces friction for users.

### 4. Code Review Effectiveness Continued
- Story 3-1: Fixed duplicate error output bug (displaying errors twice in Rich mode)
- Story 3-2: Fixed time pattern regex for plurals, added exclusion words for verb detection
- Story 3-3: Added multiple filter AND logic (Task 4.5), edge case tests

### 5. Validator Service Design
The separation of `ValidationResult` and `ValidationSummary` dataclasses from the core validation logic made testing straightforward. Using `jsonschema.Draft202012Validator` matched the schema's draft version correctly.

## Challenges & Lessons Learned

### 1. Duplicate Output Bug (Story 3-1)
**Pattern:** In Rich mode, errors were displayed by the output function AND then again by the exception handler when raising `ValidationError` for the exit code, causing duplicate error messages.

**Solution:** Both output modes use `sys.exit()` directly instead of raising an exception after displaying output.

**Lesson:** When output is handled before raising exceptions for exit codes, ensure the exception handler doesn't also produce output. Consider separating "display" from "signal exit code" responsibilities.

### 2. Regex Edge Cases (Story 3-2)
**Pattern:** The `_has_quantification` function initially missed time patterns like "30 mins" or "5 days" (with plural 's'). Code review caught this gap.

**Solution:** Updated regex patterns to handle plural time units: `r"\d+\s*(?:ms|secs?|mins?|hours?|days?)"`.

**Lesson:** When building regex patterns for natural language, explicitly test singular/plural variants and common abbreviations.

### 3. Story Dev Notes vs Actual Code (Multiple Stories)
**Pattern:** Stories had Dev Notes with code samples that diverged from final implementation during code review fixes. Story 3-3 addressed this by wrapping outdated code in a `<details>` block with "(outdated - click to expand)" note.

**Lesson:** Either update Dev Notes during implementation or explicitly mark them as "planning guidance" (not source of truth). The `<details>` deprecation pattern from Story 3-3 is a good solution.

### 4. Lambda Functions vs Named Functions (Story 3-3)
**Pattern:** Initial sorting implementation used lambdas, but ruff E731 flagged them as violations.

**Solution:** Converted to named sort key functions (`_sort_key_date`, `_sort_key_title`, `_sort_key_confidence`).

**Lesson:** Prefer named functions over lambdas for sort keys - improves readability and satisfies linting rules.

## Code Review Statistics

| Story | Issues Found | HIGH | MEDIUM | LOW | Fixed |
|-------|--------------|------|--------|-----|-------|
| 3-1 | 5 | 1 | 3 | 1 | 5 |
| 3-2 | 9 | 0 | 5 | 4 | 9 |
| 3-3 | 5 | 0 | 3 | 2 | 5 |

**Total:** 19 issues found, 19 fixed

**Notable:** The one HIGH severity issue (Story 3-1) was the duplicate error output bug - a real usability problem that would have confused users. Code reviews continue to find meaningful issues.

## Previous Retrospective Follow-Through

From Epic 2 retrospective action items:

| Action Item | Status | Evidence |
|-------------|--------|----------|
| Test list validators with edge cases | ✅ Applied | Content validator tests include edge cases for verb detection, quantification patterns |
| Keep story documentation updated | ⚠️ Partial | Story 3-3 used deprecation pattern; some drift in Stories 3-1, 3-2 |
| Continue adversarial code reviews | ✅ Applied | All 3 stories went through review, 19 issues found and fixed |
| Maintain `__init__.py` exports and output mode tests | ✅ Applied | JSON mode tests in all stories, no export issues found |

## Technical Debt

### Debt Status
- No critical debt items requiring immediate action
- Documentation drift addressed via deprecation pattern
- Codebase remains clean with 100% mypy --strict compliance
- No shortcuts taken during implementation

## Action Items for Future Epics

| ID | Action | Owner | Status |
|----|--------|-------|--------|
| 1 | Mark Dev Notes code as "planning guidance" or keep updated | All Devs | New |
| 2 | Continue testing regex patterns with edge cases (plurals, variants) | All Devs | New |
| 3 | Watch for duplicate output patterns (display + exception handler) | All Devs | New |
| 4 | Continue adversarial code reviews for each story | SM | Ongoing |
| 5 | Maintain `__init__.py` exports and output mode tests | All Devs | Ongoing |
| 6 | Prefer named functions over lambdas for sort keys | All Devs | Ongoing |

## Next Epic Preparation

### Epic 4: Resume Planning & Explainability
- **Goal**: Users can run `resume plan` and see exactly what will be included/excluded with reasons (Journey 2: "The Plan")
- **Stories**: 7 (4-1 through 4-7)
- **FRs Covered**: FR12, FR13, FR14, FR15, FR16, FR17, FR18, FR19

### Dependencies on Epic 3
- Validator service for ensuring Work Units are valid before ranking
- List command infrastructure (loading, filtering) useful for plan selection
- Content quality validators potentially useful for rewrite suggestions (FR17)

### Readiness Assessment
- **Foundation**: Complete and stable (Epics 1-3)
- **Dependencies**: All satisfied
- **Blockers**: None identified
- **Ready to Start**: Yes

### Epic 4 Technical Preview
Epic 4 is the "killer feature" - the Terraform-style preview that no other resume tool offers:
- Job description parsing and skill extraction
- BM25 ranking algorithm for Work Unit selection
- Explainability: relevance scores, match rationale, exclusion reasons
- Skill gap analysis against JD requirements
- Plan persistence for iterative refinement

## Team Acknowledgments

Epic 3 delivered comprehensive validation and discovery capabilities. All 3 stories completed with strong test coverage (125+ new tests) and clean code quality metrics. The adversarial code review process continues to prove its value, catching the duplicate output bug and regex edge cases.

Key achievements:
- Schema validation with actionable feedback (FR6, FR7)
- Content quality checks beyond basic validation
- Rich table listing with sophisticated filtering (FR8)
- 100% acceptance criteria coverage

Journey preparation is complete. Users can now create Work Units (Epic 2), validate them with helpful feedback, and browse their collection with confidence (Epic 3). The foundation is ready for Epic 4's planning intelligence.

---

*Retrospective conducted by Bob (Scrum Master) with Joshua Magady (Project Lead)*
