Plan Findings Create Skill

Retroactively extract findings from completed plan phases when findings weren't recorded during implementation.

Process

1. •

   Identify the target plan:

   • •If the user provides a plan number (e.g., /plan:findings-create 0018), use that plan directly
   • •If no number is provided, scan for in-progress plans:
     • •Look for .gumbo/plans/*/task-list.md files (exclude .gumbo/plans/archive/)
     • •Check which plans have completed tasks but no findings/ directory (or sparse findings)
     • •If one plan qualifies, use it
     • •If multiple plans qualify, list them and ask the user to choose
     • •If no plans qualify, check .gumbo/plans/archive/ and offer those
2. •

   Gather implementation context:

   Read the plan's state to understand what was done:

   • •Read implementation-plan.md for the intended approach
   • •Read task-list.md to identify completed phases and tasks
   • •Read .plan-state.json for:
     • •commits array — commit SHAs from completed phases
     • •last_session_notes — notes about what happened
     • •current_task — where work stopped
   • •Read task files in tasks/ for what was planned vs. what may have changed
3. •

   Review commits for each completed phase:

   For each commit SHA in .plan-state.json:

   • •Run git log --format='%H %s' <sha> to get the commit message
   • •Run git diff <sha>~1..<sha> --stat to see what files changed
   • •Run git diff <sha>~1..<sha> to review the actual changes
   • •Compare changes against what the task files specified

   If no commits are recorded but tasks are checked off:

   • •Use git log --oneline to find likely commits by message pattern (feat(plan-NNNN))
   • •Review those commits instead
4. •

   Identify findings by comparing plan vs. reality:

   For each completed task/phase, look for:

   • •Diversions: Code that differs from what the task file specified. Why did the approach change?
   • •Discoveries: Unexpected behavior encountered. New understanding of how the code works.
   • •Plan errors: Tasks that assumed something incorrect. Missing steps that had to be improvised.
   • •TODOs: Comments with TODO, FIXME, HACK, or WORKAROUND in the committed code.
   • •Cleanup items: Code that works but could be improved. Temporary scaffolding left in place.
   • •Notes: Important context that future work should know about.

   Also search the committed code:

   • •Grep for TODO, FIXME, HACK, WORKAROUND, XXX in changed files
   • •Look for commented-out code or temporary implementations
   • •Check test files for #[ignore] or @skip markers
5. •

   Present findings to the user:

   code

   **Plan:** `.gumbo/plans/NNNN-feature-name/`
   **Phases reviewed:** N completed phases (M commits)
   **Findings identified:** K total
   
   | # | Finding | Type | Phase/Task | Source |
   |---|---------|------|------------|--------|
   | 1 | [Short title] | diversion | Phase 2 / Task 2.1 | Commit abc1234 |
   | 2 | [Short title] | todo | Phase 3 / Task 3.2 | TODO in src/foo.rs:42 |
   | 3 | [Short title] | discovery | Phase 1 / Task 1.3 | Commit def5678 |
   
   Should I write these as finding files in `.gumbo/plans/NNNN-name/findings/`?
   You can adjust, add, or remove findings before I write them.
   

6. •

   Wait for user approval before writing findings.

7. •

   Write finding files:

   • •

     Create .gumbo/plans/NNNN-name/findings/ directory if it doesn't exist

   • •

     Write each finding as an individual markdown file

   • •

     Use descriptive filenames: findings/todo-cleanup-unused-helpers.md

   • •

     Follow the standard finding format:

     markdown

     # Finding: Short Title
     
     **Type:** discovery | diversion | plan-error | note | todo | cleanup
     **Task:** 2.1
     **Date:** YYYY-MM-DD
     **Source:** Commit abc1234 | TODO in src/foo.rs:42 | Observed during review
     
     ## Details
     [What was found/changed/wrong]
     
     ## Impact
     [How this affects the current plan or future work]
     
     ## Action Items
     - [ ] Concrete next step (if any)
     

8. •

   Report results:

   code

   **Findings written:** N files in `.gumbo/plans/NNNN-name/findings/`
   
   - findings/diversion-changed-routing-approach.md
   - findings/todo-cleanup-unused-helpers.md
   - findings/discovery-diamond-attachment-behavior.md
   
   Run `/plan:findings-resume NNNN` to triage these into issues and research.
   

When to Use This Skill

• •A plan has completed phases but no findings/ directory
• •You finished implementing and forgot to record findings along the way
• •You want to do a retrospective review of what changed vs. what was planned
• •Before archiving a plan, to capture learnings

Example Output

Plan: .gumbo/plans/0018-lr-rl-remaining-fixes/ Phases reviewed: 3 completed phases (3 commits) Findings identified: 4 total

Should I write these as finding files in .gumbo/plans/0018-lr-rl-remaining-fixes/findings/?