feat: AI-First Dotfiles Enhancement Sprint (5 features)

.claude/command-templates/close-issue.md

@@ -19,7 +19,7 @@ When following the procedure:
 ## Final Step: Retro
 Let's retro this context and wring out the gleanings.
 
-{{ INJECT:principles/continuous-improvement.md }}
+{{ INJECT:principles/eager-evolution.md }}
 
 **Consider capturing any ghost procedures** that emerged during this work - see [Procedure Creation](knowledge/procedures/procedure-creation.md).
 

.claude/command-templates/create-issue.md

@@ -0,0 +1,25 @@
+---
+name: create-issue
+description: Create GitHub issue with intelligent type detection and template selection
+---
+
+# Create GitHub Issue
+
+I'll help you create a GitHub issue with the appropriate template and context.
+
+{{ INJECT:procedures/github-issue-creation.md }}
+
+## Request Analysis
+
+Please provide:
+1. **What you want to create an issue for**
+2. **Any specific details or context**
+3. **Whether this is for dotfiles or another repository**
+
+I'll:
+- Auto-detect the issue type
+- Suggest the best template
+- Link relevant procedures
+- Include appropriate labels
+
+What would you like to create an issue for?

.claude/command-templates/retro.md

@@ -1,10 +1,10 @@
 ---
 name: retro
-description: Mine gleanings through continuous improvement principle
+description: Mine gleanings through eager evolution of living systems
 ---
 
 Timeout - let's retro this context and wring out the gleanings.
 
-{{ INJECT:principles/continuous-improvement.md }}
+{{ INJECT:procedures/post-pr-mini-retro.md }}
 
-You drive - I'll support with observations when you ask.
+{{ INJECT:principles/eager-evolution.md }}

.github/ISSUE_TEMPLATE/close-issue-guide.md

@@ -0,0 +1,94 @@
+# Close Issue Detailed Guide
+
+Complete workflow for analyzing and implementing GitHub issues.
+
+## Step 1: Analyze the Issue
+
+Use `mcp__github__get_issue` to read the issue and determine:
+- Is this already resolved? → Quick close
+- Does this need implementation? → Full workflow
+- Is this invalid/duplicate? → Close with explanation
+- **Is this a spike?** → Spike workflow (no PR)
+- **Repository check**: If issue requires git operations in a different repo, STOP and ask human to restart session there. Claude Code cannot `cd` outside initial directory tree, breaking git workflows.
+- Check recent merged PRs for similar patterns → `mcp__github__list_pull_requests` (state: "closed")
+- Get issue comments with `mcp__github__get_issue_comments` to enrich understanding
+
+**Clarity opportunity**: If the issue contains vague language ("doesn't work", "should handle", "it depends"), consider exploring with EARS patterns to surface hidden assumptions and edge cases. This often reveals interesting test scenarios and sparks productive conversations about the real requirements. See [EARS Requirements](../../knowledge/procedures/ears-requirements.md) for conversation-driven discovery techniques.
+
+## Quick Close Path
+
+If the issue is already resolved, invalid, or duplicate:
+1. Add explanatory comment with `mcp__github__add_issue_comment`
+2. Close with `mcp__github__update_issue` (state: "closed")
+3. Done!
+
+## Spike Workflow Path
+
+If the issue is a spike:
+1. Research. Prototype. Document findings.
+2. Comment findings with `mcp__github__add_issue_comment`
+3. Discuss with human
+4. Close issue when done
+5. **NO PR** - spikes deliver knowledge, not code
+
+## Full Implementation Path
+
+If the issue needs implementation:
+
+### 1. Set Up Development
+Follow [Worktree Workflow](../../knowledge/procedures/worktree-workflow.md) to create isolated development environment.
+
+### 2. Implement Solution
+Apply tracer bullets methodology:
+
+**First, establish your target:**
+- Define clear success criteria for the issue resolution
+- Understand what failure looks like (how to detect when it's NOT fixed)
+- Create verification methods (tests, checks, validations) that can detect hits/misses
+
+**Then iterate with tracer rounds:**
+- Fire and miss: See verifications fail (confirms target detection works)
+- Adjust aim: Modify implementation while keeping target stable
+- Fire again: Run verifications to check progress
+- Use TodoWrite to track verified hits on target
+- Each commit is a confirmed hit - only commit code that moves toward the target
+
+**Natural behaviors that emerge:**
+- Test-first development (you need a target before you can aim)
+- Incremental progress through verified steps
+- Progressive refinement from rough to precise shots
+- Clear trajectory visible through commit history
+
+Follow [Git Workflow](../../knowledge/procedures/git-workflow.md) for commit standards.
+
+### 3. Create Pull Request
+- Push the feature branch to remote
+- Look for PR template:
+  - First check local repo: `.github/PULL_REQUEST_TEMPLATE.md`
+  - If not found, use dotfiles fallback: `~/ppv/pillars/dotfiles/.github/PULL_REQUEST_TEMPLATE.md`
+  - Inform which template is being used for transparency
+- Create PR with `mcp__github__create_pull_request` following the discovered template
+- Add "Conduct post-PR mini retro" to your todo list
+
+### 4. Iterate Based on Feedback
+Keep worktree active for PR adjustments based on the tracer bullets principle. Only cleanup after PR is merged.
+
+If MCP tools fail during implementation, follow [MCP Error Reporting](../../knowledge/procedures/mcp-error-reporting.md) to create self-healing feedback loop.
+
+## Decision Matrix
+
+- **Spike label** → Spike workflow (research only)
+- **Bug report with clear reproduction** → Implementation path
+- **Feature request approved by maintainer** → Implementation path  
+- **Question already answered** → Quick close with link
+- **Duplicate issue** → Quick close referencing original
+- **Invalid/out of scope** → Quick close with explanation
+- **Implemented in recent PR** → Quick close with PR reference
+
+Remember: Act agentically. Make the decision and execute.
+
+## See Also
+
+- [Issue to PR Workflow](../../knowledge/procedures/issue-to-pr-workflow.md) - High-level workflow overview
+- [Tracer Bullets](../../knowledge/principles/tracer-bullets.md) - Target-first development
+- [Post-PR Mini Retro](../../knowledge/procedures/post-pr-mini-retro.md) - Learning from implementation

docs/procedures/git-workflow-detailed.md

@@ -0,0 +1,38 @@
+# Git Workflow Detailed Rules
+
+## Branch Management
+
+**Core principle: Working on main creates future work**. Every commit on main that should be on a feature branch guarantees recovery work: cherry-picking, rebasing, or complex git surgery. This violates the subtraction principle - we're adding unnecessary future tasks.
+
+**Go slow to go fast**: The recovery tax compounds invisibly. A stale starting point pollutes every subsequent action - your PR carries ghost commits, review gets clouded by unintended diffs, context windows fill with noise. The principle isn't about git mechanics but about preserving clarity of intent. When we rush past orientation, we mortgage our future attention.
+
+### Quick orientation checks (prevent future cleanup)
+1. `mcp__git__git_status` - Where am I? What's already changed?
+   → [subtraction-creates-value](../../knowledge/principles/subtraction-creates-value.md) (avoid recovery tax)
+2. Check current branch - Am I on main? Do I have uncommitted work?
+3. **Is main current?** - `git fetch && git status` - Behind origin/main means your PR will include unwanted commits
+   → [subtraction-creates-value](../../knowledge/principles/subtraction-creates-value.md)
+4. If changes exist on main - commit them properly or stash before branching
+
+Starting from a stale foundation guarantees the recovery tax - double work to achieve what orientation would have prevented.
+
+### Standards (not methods)
+- Branch naming: `type/description` (e.g., `feature/add-authentication`, `fix/login-bug`)
+- Issue suffix: `type/description-123` (e.g., `feature/add-authentication-512`)
+- Order: Check surroundings → create branch → switch → work → commit
+  → [subtraction-creates-value](../../knowledge/principles/subtraction-creates-value.md) (prevent recovery work)
+
+These standards make intent visible and prevent the recovery tax.
+
+## Directory to Symlink Conversions
+When converting a directory to a symlink (or vice versa), it's safer to use different names or do it in separate commits to avoid git tree corruption.
+
+**Why**: Git can create invalid tree objects when the same path transitions from directory to symlink within a single commit, causing push failures with "duplicateEntries" errors.
+
+**Safe approaches**:
+1. Use different names (e.g., rename directory first, then create symlink)
+2. Split into separate commits (remove directory in one commit, add symlink in another)
+3. Create fresh branch from clean state if corruption occurs
+
+## Think-Tank Content in Worktrees
+**CRITICAL**: Never add think-tank notes or personal content to worktree locations. Worktrees are temporary directories that will be deleted when cleanup occurs. Always use the main repository at `/think-tank/` for any persistent personal content, notes, or documentation.

docs/procedures/issue-to-pr-detailed-workflow.md

@@ -0,0 +1,106 @@
+# Issue-to-PR Detailed Workflow
+
+The complete mechanical workflow from GitHub issue to merged pull request.
+
+## The Complete Flow
+
+```
+GitHub Issue → Planning Mode → Implementation → Pull Request → Review → Merge
+```
+
+## Step-by-Step Mechanics
+
+### 1. GitHub Issue Defines the Work
+
+Every task starts as a GitHub issue:
+- Clear problem statement  
+- Success criteria defined
+- Labels automatically assigned by Claude Code GitHub Action based on principles
+
+**Anti-pattern**: Starting work without an issue leads to scope creep and unclear PRs.
+
+### 2. Planning Mode Review
+
+Run `/close-issue <number>` with planning mode (default):
+- Claude analyzes the issue
+- Presents a plan for review
+- You approve, refine, or reject
+
+**Key insight**: This shifts you from "driving" to "managing" - you review plans, not implementation details.
+
+### 3. Implementation in Isolation
+
+Once plan is approved:
+- Automatic worktree creation for complete isolation
+- Claude implements in focused sessions
+- Each commit represents verified progress
+
+**Tools involved**:
+- [Git worktrees](../../knowledge/procedures/worktree-workflow.md) for isolation
+- [Git workflow](../../knowledge/procedures/git-workflow.md) for commits
+- MCP tools for file operations
+
+### 4. Pull Request Packages the Solution
+
+Implementation complete:
+- Push branch to remote
+- Create PR referencing "Closes #<issue>"
+- PR description explains the solution
+
+**Quality gates**:
+- Small, focused changes (planning mode enables this)
+- Clear connection to original issue
+- Tests pass, linting clean
+
+### 5. Review Completes the Cycle
+
+PR review happens at the right altitude:
+- Review the solution, not individual lines
+- Verify it solves the original issue
+- Merge when approved
+
+### 6. Post-Merge Workflow
+
+After merging via GitHub UI:
+1. Exit Claude Code
+2. `git checkout main`
+3. `git pull origin main`
+4. `source setup.sh`
+5. Start new terminal session
+6. Restart Claude Code:
+   - Resume last chat for context continuity
+   - Or start fresh for new work
+
+**Note**: This manual process ensures clean environment and updated configurations.
+
+### 7. Optional: Post-PR Retro
+
+For significant work:
+- Run [post-PR mini retro](../../knowledge/procedures/post-pr-mini-retro.md)
+- Capture learnings
+- Update procedures if needed
+- Document any ghost procedures discovered - see [Procedure Creation](../../knowledge/procedures/procedure-creation.md)
+
+## Why This Works
+
+1. **Clear boundaries**: Issues define WHAT, PRs deliver solutions
+2. **Parallel execution**: Multiple issues → multiple agents → multiple PRs
+3. **Quality through planning**: Better plans = better PRs
+4. **Reduced cognitive load**: Review plans and PRs, not live coding
+
+## Configuration
+
+Planning mode should be enabled by default for all users:
+```bash
+# In ~/.claude/settings.json
+{
+  "defaultMode": "plan"
+}
+```
+
+**Recommendation**: Add this to your `setup.sh` or dotfiles to ensure all team members start with planning mode enabled. This enforces OSE principles from day one.
+
+## Related
+
+- [tmux + git worktrees + Claude Code + Planning Mode](../../knowledge/procedures/tmux-git-worktrees-claude-code.md) - The complete productivity system
+- [OSE Principle](../../knowledge/principles/ose.md) - Why this workflow embodies management over doing

docs/procedures/procedure-creation-guide.md

@@ -0,0 +1,97 @@
+# Procedure Creation Guide
+
+How to capture ghost procedures and improve existing ones, inspired by Sam Carpenter's "Work the System".
+
+## Ghost Procedures
+
+Ghost procedures are the unwritten processes we follow repeatedly but haven't documented. Like Sam Carpenter discovered after 25 years of firefighting at his telephone answering service, these hidden procedures are everywhere - we just need to capture them.
+
+## When to Create a New Procedure
+
+Create a procedure when you:
+- Do something more than twice
+- Explain how to do something
+- Find yourself saying "the way we usually..."
+- Discover an undocumented pattern
+- Hit the same problem repeatedly
+- Notice tribal knowledge that should be shared
+
+## When to Improve Existing Procedures
+
+Improve a procedure when:
+- It feels incomplete or unclear
+- You had to figure out missing steps
+- The context has changed
+- You found a better way
+- It references outdated tools/methods
+
+## Creating a New Procedure
+
+1. **Check if it exists** - Look in `procedures/` first
+2. **Name it clearly** - Use verb-noun format (e.g., `manage-dependencies.md`)
+3. **Start simple** - Even a rough draft is better than nothing
+4. **Follow the template** below
+5. **Link it** - Add to relevant sections in ai-index.md
+
+**Quick capture option**: Use the [Procedure Documentation issue template](/.github/ISSUE_TEMPLATE/procedure-documentation.md) to quickly document a ghost procedure for later formalization.
+
+## Procedure Template
+
+```markdown
+# [Procedure Name]
+
+Brief description of what this procedure accomplishes.
+
+## When to Use This
+
+Specific situations or triggers that indicate this procedure should be followed.
+
+## Prerequisites
+
+- Required tools, access, or knowledge
+- Links to related procedures
+
+## Procedure
+
+1. **Step name** - Clear action
+   - Sub-step if needed
+   - Expected outcome
+
+2. **Next step** - What to do next
+   - Details
+   - Validation
+
+## Common Issues
+
+- Known problems and solutions
+- Edge cases to watch for
+
+## See Also
+
+- Related procedures
+- Relevant principles
+```
+
+## Improving Procedures
+
+When improving:
+1. **Make the edit** - Don't create v2 files (versioning mindset)
+2. **Add what's missing** - Fill gaps you discovered
+3. **Remove what's outdated** - Subtraction creates value
+4. **Test it mentally** - Would this help someone new?
+
+## The Carpenter Principle
+
+Sam Carpenter transformed his business by documenting every procedure, no matter how small. After 25 years of chaos, systematic documentation gave him control. Every ghost procedure you capture reduces future firefighting.
+
+Remember: **Perfect is the enemy of good**. A rough procedure that exists beats a perfect one that doesn't.
+
+## Examples of Ghost Procedures to Capture
+
+- How we handle MCP server updates
+- Steps for debugging flaky tests
+- Process for reviewing PRs
+- Method for setting up new machines
+- Workflow for handling service outages
+
+Start capturing - every documented procedure is one less fire to fight!