groundswell 0.0.1 → 0.0.2

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M4T2S2/research/ULTRATHINK_PRP_PLAN.md

@@ -0,0 +1,301 @@
+# ULTRATHINK PRP Writing Plan for P1.M4.T2.S2
+
+## Objective
+Create a comprehensive PRP for updating CHANGELOG.md with bug fix summary from P1.M4.T2.S1.
+
+## Template Section Mapping
+
+### 1. Goal Section
+**Source Data**: Bug Fix Summary from `/plan/bugfix/BUG_FIX_SUMMARY.md`
+
+**Feature Goal**: Update CHANGELOG.md following Keep a Changelog format with all bug fixes categorized by severity.
+
+**Deliverable**: Updated CHANGELOG.md file with new version entry documenting all bug fixes.
+
+**Success Definition**:
+- CHANGELOG.md updated with new version entry
+- All 8 bug fixes documented (1 Critical, 3 Major, 4 Minor)
+- Follows existing format from previous entries
+- Semantic versioning correctly applied (PATCH release since no breaking changes)
+
+### 2. User Persona (Not Applicable)
+This is an internal documentation task - no end user persona. Target audience is developers and project maintainers.
+
+### 3. Why Section
+**Business Value**:
+- Provides clear release notes for users
+- Documents bug fixes for transparency
+- Follows industry best practices (Keep a Changelog)
+- Enables semantic versioning decisions
+
+**Problems Solved**:
+- Without changelog, users have no visibility into what was fixed
+- Enables informed upgrade decisions
+- Provides audit trail for project history
+
+### 4. What Section
+**User-Visible Behavior**: None (internal documentation)
+
+**Success Criteria**:
+- [ ] CHANGELOG.md contains new version entry
+- [ ] All bug fixes from BUG_FIX_SUMMARY.md are documented
+- [ ] Format matches existing changelog entries
+- [ ] Version comparison links are correct
+
+### 5. All Needed Context
+
+#### Documentation & References
+
+```yaml
+# MUST READ - Include these in your context window
+- url: https://keepachangelog.com/en/1.1.0/
+  why: Standard changelog format specification - use for structure and section ordering
+  critical: Use "Added", "Changed", "Deprecated", "Removed", "Fixed" categories exactly
+
+- url: https://semver.org/spec/v2.0.0.html
+  why: Semantic versioning rules - this is a PATCH release (0.0.2 -> 0.0.3) since no breaking changes
+  critical: Bug fixes always trigger PATCH version increment
+
+- file: /home/dustin/projects/groundswell/CHANGELOG.md
+  why: Reference existing format, style, and structure - copy the exact pattern
+  pattern: Version heading with date, categories (Fixed, Added), code references with links, migration guide section, test coverage section
+  gotcha: Current latest is 0.0.2, new entry should be 0.0.3 (or 0.0.3 since 0.0.2 already exists)
+
+- file: /home/dustin/projects/groundswell/plan/bugfix/BUG_FIX_SUMMARY.md
+  why: Source document containing all bug fixes to be documented
+  pattern: Organized by severity (Critical, Major, Minor) with detailed descriptions
+  gotcha: Contains 8 bug fixes total - need to extract key points for changelog
+
+- file: /home/dustin/projects/groundswell/package.json
+  why: Current version is 0.0.1 but changelog shows 0.0.2 - use changelog as source of truth
+  gotcha: Version discrepancy between package.json and CHANGELOG.md - follow changelog progression
+```
+
+#### Current Codebase Tree (Relevant Files Only)
+
+```bash
+groundswell/
+├── CHANGELOG.md                    # TARGET FILE - Update with new version entry
+├── package.json                    # Contains version 0.0.1 (out of sync with changelog)
+└── plan/
+    └── bugfix/
+        └── BUG_FIX_SUMMARY.md      # SOURCE FILE - Contains bug fixes to document
+```
+
+#### Desired Codebase Tree After Implementation
+
+```bash
+groundswell/
+├── CHANGELOG.md                    # UPDATED - New version entry added at top
+├── package.json                    # May need version bump to match changelog
+```
+
+#### Known Gotchas
+
+```markdown
+# CRITICAL: Version discrepancy
+# package.json shows 0.0.1 but CHANGELOG.md shows 0.0.2 as latest
+# Solution: Follow CHANGELOG.md progression (0.0.2 -> 0.0.3)
+
+# CRITICAL: Format consistency
+# Each bug fix entry must match existing style:
+# - Bold category/name prefix
+# - Description starting with lowercase
+# - Code references with GitHub-style links: src/file.ts:line-range
+# - Implementation links in subsections
+
+# CRITICAL: Section ordering
+# Must follow Keep a Changelog order: Fixed, Added, Changed, Deprecated, Removed, Security
+# For bug fixes: Primary category is "Fixed"
+
+# CRITICAL: Version comparison links
+# Must update the links at bottom of CHANGELOG.md:
+# [Unreleased]: https://github.com/dustin/groundswell/compare/v0.0.3...HEAD
+# [0.0.3]: https://github.com/dustin/groundswell/compare/v0.0.2...v0.0.3
+```
+
+### 6. Implementation Blueprint
+
+#### Data Models and Structure
+
+Not applicable - this is a documentation update task.
+
+#### Implementation Tasks (Dependency-Ordered)
+
+```yaml
+Task 1: DETERMINE new version number
+  - ANALYZE: Current latest version in CHANGELOG.md (0.0.2)
+  - DETERMINE: Version increment type (PATCH = 0.0.3)
+  - REASON: No breaking changes identified in BUG_FIX_SUMMARY.md
+  - OUTPUT: New version = 0.0.3
+
+Task 2: EXTRACT bug fix summaries from BUG_FIX_SUMMARY.md
+  - READ: /plan/bugfix/BUG_FIX_SUMMARY.md
+  - EXTRACT: 8 bug fixes organized by severity
+  - FORMAT: Convert detailed descriptions to changelog-style entries
+  - CATEGORIZE: All go under "Fixed" section
+  - REFERENCE: Include src/file.ts:line-range for each fix
+
+Task 3: CREATE new version entry in CHANGELOG.md
+  - POSITION: Insert after [Unreleased] section, before [0.0.2]
+  - FORMAT: Follow exact pattern from existing entries
+  - INCLUDE:
+    * Version heading: ## [0.0.3] - YYYY-MM-DD
+    * Fixed section with all 8 bug fixes
+    * Migration Guide section (if needed - likely none)
+    * Test Coverage section
+    * Implementation Details with code references
+
+Task 4: UPDATE version comparison links at bottom of CHANGELOG.md
+  - UPDATE: [Unreleased] link to compare v0.0.3...HEAD
+  - ADD: [0.0.3] link to compare v0.0.2...v0.0.3
+  - PRESERVE: All existing comparison links
+
+Task 5: VERIFY package.json version (Optional)
+  - CHECK: If package.json should be updated to match
+  - DECIDE: Based on project conventions (may be out of scope)
+  - NOTE: Currently package.json is 0.0.1, changelog shows 0.0.2
+```
+
+#### Implementation Patterns & Key Details
+
+```markdown
+# Bug Fix Entry Pattern (from existing CHANGELOG.md):
+
+- **{Brief Fix Name}**: {Description starting with lowercase}.
+  - Implementation: [src/path/to/file.ts:line-range](src/path/to/file.ts#Lline-Lline)
+
+# Severity indicators (optional, from bug fix summary):
+- Can use **Critical**, **Major**, **Minor** prefixes if helpful
+- Or organize by severity within Fixed section
+
+# Date format:
+- Use ISO date: YYYY-MM-DD
+- Use today's date: 2026-01-12 (from environment)
+
+# Code reference format:
+- Use relative paths from repo root: src/core/workflow.ts
+- Use GitHub-style anchors: #L98-L111 for line ranges
+- Create markdown links: [src/core/workflow.ts:98-111](src/core/workflow.ts#L98-L111)
+```
+
+#### Integration Points
+
+```yaml
+FILES:
+  - modify: CHANGELOG.md
+    add: New version entry ## [0.0.3] - 2026-01-12
+    update: Version comparison links at bottom
+
+  - consider: package.json
+    may_need: Version bump to 0.0.3
+    note: Currently out of sync (0.0.1 vs 0.0.2 in changelog)
+```
+
+### 7. Validation Loop
+
+#### Level 1: Syntax & Style
+
+```bash
+# Verify markdown syntax
+npx prettier --check CHANGELOG.md
+
+# Or just visual inspection - no syntax for markdown
+
+# Expected: No markdown rendering errors
+```
+
+#### Level 2: Content Validation
+
+```bash
+# Count bug fixes documented
+grep -c "^- \*\*" CHANGELOG.md | head -1  # Should show 8 new entries
+
+# Verify version links are correct
+grep "\[0.0.3\]" CHANGELOG.md
+
+# Verify format matches existing entries
+# Visual comparison with [0.0.2] section
+
+# Expected:
+# - 8 bug fixes listed
+# - Version links present
+# - Format matches existing entries
+```
+
+#### Level 3: Link Validation
+
+```bash
+# Verify code reference links are valid
+test -f src/core/logger.ts && echo "logger.ts exists"
+test -f src/decorators/task.ts && echo "task.ts exists"
+test -f src/core/workflow.ts && echo "workflow.ts exists"
+
+# Expected: All referenced files exist
+```
+
+#### Level 4: Release Readiness
+
+```bash
+# Verify no TODO placeholders in changelog
+grep -i "TODO\|TBD\|XXX" CHANGELOG.md || echo "No placeholders found"
+
+# Check date is current (2026-01-12)
+grep "2026-01-12" CHANGELOG.md
+
+# Expected: No placeholders, correct date
+```
+
+### 8. Final Validation Checklist
+
+#### Technical Validation
+- [ ] CHANGELOG.md updated with new version entry
+- [ ] All 8 bug fixes from BUG_FIX_SUMMARY.md are documented
+- [ ] Code references use correct file paths and line ranges
+- [ ] Version comparison links updated correctly
+- [ ] No markdown syntax errors
+
+#### Content Validation
+- [ ] Version number follows semantic versioning (PATCH = 0.0.3)
+- [ ] Date is correct (2026-01-12)
+- [ ] Format matches existing changelog entries
+- [ ] All code references point to valid locations
+- [ ] Migration guide included if needed (likely none for this release)
+
+#### Quality Validation
+- [ ] Bug fixes are clearly described
+- [ ] Severity levels are indicated if needed
+- [ ] Test coverage section is included
+- [ ] Implementation details with code links are provided
+
+### 9. Anti-Patterns to Avoid
+
+- ❌ Don't include TODO placeholders - complete all content
+- ❌ Don't use vague descriptions - be specific about what was fixed
+- ❌ Don't forget to update version comparison links
+- ❌ Don't mix bug fixes with new features - use "Fixed" category
+- ❌ Don't break existing format - follow exact pattern from [0.0.2]
+- ❌ Don't use incorrect line ranges - verify all code references
+- ❌ Don't skip test coverage documentation - include test file references
+
+## Research Summary
+
+### Key Findings
+
+1. **Project follows Keep a Changelog format** - Strict adherence required
+2. **Latest version is 0.0.2** - New version should be 0.0.3 (PATCH release)
+3. **No breaking changes** - Confirmed in BUG_FIX_SUMMARY.md
+4. **Version discrepancy** - package.json shows 0.0.1 but changelog shows 0.0.2
+5. **8 bug fixes total** - 1 Critical, 3 Major, 4 Minor
+6. **All fixes have code locations** - Can link directly to source
+
+### Source Material
+
+- **Bug Fix Summary**: `/plan/bugfix/BUG_FIX_SUMMARY.md` (962 lines)
+- **Current CHANGELOG**: `/CHANGELOG.md` (110 lines)
+- **Package Version**: `/package.json` shows 0.0.1
+
+### External References
+
+- Keep a Changelog: https://keepachangelog.com/en/1.1.0/
+- Semantic Versioning: https://semver.org/spec/v2.0.0.html