@accelerationguy/accel 1.0.0

package/modules/drive/src/workflows/debug.md

@@ -0,0 +1,292 @@
+<purpose>
+Systematic debugging with persistent state that survives context resets. The debug file IS the debugging brain - create it immediately and update it continuously.
+
+You are the debugger. The user knows what's wrong (behavior), not why (root cause). Gather symptoms, then investigate autonomously.
+</purpose>
+
+<philosophy>
+**User = reporter. Claude = investigator.**
+
+The user knows:
+- What they expected to happen
+- What actually happened
+- Any error messages they saw
+- When it started / if it ever worked
+
+The user does NOT know (and shouldn't be asked):
+- What's causing the bug
+- Which file has the problem
+- What the fix should be
+
+Ask about experience. Investigate the cause yourself.
+</philosophy>
+
+<template>
+@src/templates/DEBUG.md
+</template>
+
+<process>
+
+<step name="check_active_session">
+**First: Check for active debug sessions**
+
+```bash
+ls .drive/debug/*.md 2>/dev/null | grep -v resolved
+```
+
+**If active sessions exist AND no $ARGUMENTS provided:**
+
+Read each file's frontmatter (status, trigger) and Current Focus (hypothesis, next_action).
+
+Display inline:
+
+```
+## Active Debug Sessions
+
+| # | Slug | Status | Hypothesis | Next Action |
+|---|------|--------|------------|-------------|
+| 1 | auth-logout | investigating | Token refresh not called | Check console output |
+| 2 | api-timeout | gathering | - | Gather symptoms |
+
+Reply with a number to resume, or describe a new issue to start fresh.
+```
+
+Wait for user response.
+
+- If user replies with number → Load that file, go to `resume_from_file`
+- If user replies with text → Treat as new issue trigger, go to `create_debug_file`
+
+**If no active sessions:**
+
+```
+No active debug sessions.
+
+Describe the issue to start debugging.
+```
+
+Wait for user to describe the issue.
+</step>
+
+<step name="create_debug_file">
+**Create debug file IMMEDIATELY**
+
+Generate slug from user input (lowercase, hyphens, max 30 chars).
+
+```bash
+mkdir -p .drive/debug
+```
+
+Create file using DEBUG.md template with initial state:
+- status: gathering
+- trigger: [verbatim user input]
+- Current Focus: next_action = "gather symptoms from user"
+
+Write to `.drive/debug/[slug].md`
+
+Proceed to `symptom_gathering`.
+</step>
+
+<step name="symptom_gathering">
+**Gather symptoms through questioning - update file after EACH answer**
+
+CRITICAL: Update the debug file after each piece of information gathered.
+
+**1. Expected behavior:**
+Use AskUserQuestion: "What should happen?"
+After answer → Update Symptoms.expected
+
+**2. Actual behavior:**
+Use AskUserQuestion: "What actually happens instead?"
+After answer → Update Symptoms.actual
+
+**3. Error messages:**
+Use AskUserQuestion: "Any error messages?"
+After answer → Update Symptoms.errors
+
+**4. When it started:**
+Use AskUserQuestion: "When did this start?"
+After answer → Update Symptoms.started
+
+**5. Reproduction:**
+Use AskUserQuestion: "How do you trigger this?"
+After answer → Update Symptoms.reproduction
+
+**6. Ready check:**
+Use AskUserQuestion: "Enough context to investigate?"
+- If "Start investigating" → Update status to "investigating", proceed to `investigation_loop`
+- If "I have more context" → receive it, update relevant field, ask again
+</step>
+
+<step name="investigation_loop">
+**Autonomous investigation - update file continuously**
+
+CRITICAL: Before EVERY action, update Current Focus. After EVERY finding, append to Evidence.
+
+**Phase 1: Initial evidence gathering**
+
+Update Current Focus:
+```
+hypothesis: gathering initial evidence
+test: examining error context and relevant code
+expecting: clues about failure point
+next_action: [specific next action]
+```
+
+1. If errors exist in Symptoms → search codebase for error text
+2. Identify relevant code area from symptoms
+3. Read relevant files COMPLETELY
+4. Run app/tests to observe behavior firsthand
+
+After EACH finding → Append to Evidence
+
+**Phase 2: Form hypothesis**
+
+Based on evidence, form SPECIFIC, FALSIFIABLE hypothesis.
+
+Update Current Focus with hypothesis, test, expecting, next_action.
+
+**Phase 3: Test hypothesis**
+
+Execute the test. ONE hypothesis at a time.
+
+Append result to Evidence.
+
+**Phase 4: Evaluate**
+
+If CONFIRMED:
+- Update Resolution.root_cause with evidence
+- Update status to "fixing"
+- Proceed to `fix_and_verify`
+
+If ELIMINATED:
+- Append to Eliminated section with evidence
+- Form new hypothesis
+- Return to Phase 2
+
+**Context management:**
+
+After significant investigation (5+ evidence entries), check if context is filling.
+If so, ensure Current Focus is fully updated and suggest:
+"Context filling up. Safe to start fresh session - debug file preserves state."
+</step>
+
+<step name="resume_from_file">
+**Resume investigation from debug file**
+
+Read the full debug file.
+
+Announce:
+```
+Resuming: [slug]
+Status: [status]
+Current hypothesis: [from Current Focus]
+Evidence gathered: [count]
+Eliminated: [count] hypotheses
+
+Continuing from: [next_action]
+```
+
+Based on status:
+- "gathering" → Continue `symptom_gathering` from where left off
+- "investigating" → Continue `investigation_loop` from Current Focus
+- "fixing" → Continue `fix_and_verify`
+- "verifying" → Continue verification
+
+The file tells you exactly where you were.
+</step>
+
+<step name="fix_and_verify">
+**Apply fix and verify**
+
+Update status to "fixing".
+
+**1. Implement minimal fix**
+
+Make the SMALLEST change that addresses root cause.
+
+Update Resolution.fix with what was changed and why.
+Update Resolution.files_changed with modified files.
+
+**Complex fixes:** If fix requires significant code changes:
+- Create a dedicated PLAN.md for the fix
+- Reference debug file in plan context
+- Debug file stays in "fixing" until plan completes
+
+**2. Verify**
+
+Update status to "verifying".
+
+Test against original Symptoms:
+- Does expected behavior now occur?
+- Are errors gone?
+- Does reproduction no longer trigger issue?
+
+If verification FAILS:
+- Append finding to Evidence
+- Update status back to "investigating"
+- Return to `investigation_loop`
+
+If verification PASSES:
+- Update Resolution.verification
+- Proceed to `archive_session`
+</step>
+
+<step name="archive_session">
+**Archive resolved debug session**
+
+Update status to "resolved".
+
+```bash
+mkdir -p .drive/debug/resolved
+mv .drive/debug/[slug].md .drive/debug/resolved/
+```
+
+Commit:
+```bash
+git add -A
+git commit -m "fix: [brief description]
+
+Root cause: [from Resolution.root_cause]
+Debug session: .drive/debug/resolved/[slug].md"
+```
+
+Report:
+```
+Debug complete.
+
+Root cause: [root_cause]
+Fix: [fix]
+Files: [files_changed]
+
+Session archived: .drive/debug/resolved/[slug].md
+```
+</step>
+
+</process>
+
+<update_rules>
+**Section update rules (from template):**
+
+| Section | Rule | When |
+|---------|------|------|
+| Frontmatter.status | OVERWRITE | Each phase transition |
+| Frontmatter.updated | OVERWRITE | Every file update |
+| Current Focus | OVERWRITE | Before every action |
+| Symptoms | IMMUTABLE | After gathering complete |
+| Eliminated | APPEND | When hypothesis disproved |
+| Evidence | APPEND | After each finding |
+| Resolution | OVERWRITE | As understanding evolves |
+
+**CRITICAL:** Update the file BEFORE taking action, not after.
+</update_rules>
+
+<success_criteria>
+- [ ] Debug file created IMMEDIATELY on command
+- [ ] File updated after EACH piece of information
+- [ ] Current Focus always reflects NOW
+- [ ] Evidence appended for every finding
+- [ ] Eliminated prevents re-investigation
+- [ ] Can resume perfectly from any context reset
+- [ ] Root cause confirmed with evidence before fixing
+- [ ] Fix verified against original symptoms
+</success_criteria>

package/modules/drive/src/workflows/discovery.md

@@ -0,0 +1,187 @@
+<purpose>
+Execute discovery at appropriate depth to inform planning decisions. Produces DISCOVERY.md with findings, recommendation, and confidence level.
+
+Distinct from research workflow: Research gathers information. Discovery makes technical decisions.
+</purpose>
+
+<when_to_use>
+- Before planning a phase with technical unknowns
+- When choosing between libraries/frameworks
+- For architectural decisions
+- When integrating new external services
+</when_to_use>
+
+<depth_levels>
+
+| Level | Name | Time | Output | When |
+|-------|------|------|--------|------|
+| 1 | Quick | 2-5 min | Verbal confirmation | Confirming known approach |
+| 2 | Standard | 15-30 min | DISCOVERY.md | Choosing between options |
+| 3 | Deep | 1+ hour | Detailed DISCOVERY.md | Novel problems, high-risk |
+
+</depth_levels>
+
+<process>
+
+<step name="determine_depth">
+**Determine discovery depth:**
+
+If $ARGUMENTS specifies depth (e.g., "deep auth options"):
+- Use specified depth
+
+Otherwise, infer from context:
+- Single known library, just verifying → Level 1 (quick)
+- Comparing 2-3 options → Level 2 (standard)
+- Novel problem, architectural decision → Level 3 (deep)
+
+Confirm with user if unclear:
+```
+Discovery for: [topic]
+Suggested depth: [level] - [rationale]
+
+Proceed? (yes / suggest different depth)
+```
+</step>
+
+<step name="level_1_quick">
+**Level 1: Quick Verification (2-5 minutes)**
+
+For: Confirming known approach still valid.
+
+1. Quick search for current state of library/approach
+2. Verify:
+   - Still actively maintained
+   - API unchanged from expectations
+   - No critical issues
+
+3. **If verified:** Proceed to planning. No DISCOVERY.md needed.
+4. **If concerns:** Escalate to Level 2.
+
+Output: Verbal confirmation to proceed.
+</step>
+
+<step name="level_2_standard">
+**Level 2: Standard Discovery (15-30 minutes)**
+
+For: Choosing between options, new integration.
+
+1. **Identify what to discover:**
+   - What options exist?
+   - Key comparison criteria?
+   - Our specific use case?
+
+2. **Research each option:**
+   Use research subagent (Task tool with Explore or general-purpose):
+   - Official documentation
+   - Current version/status
+   - Key features for our use case
+
+3. **Compare options:**
+   - Build comparison table
+   - Note pros/cons for each
+   - Identify deal-breakers
+
+4. **Reference quality patterns:**
+   @src/references/research-quality-control.md
+   - Cross-verify findings
+   - Check source currency
+   - Assign confidence
+
+5. **Create DISCOVERY.md:**
+   Use template: @src/templates/DISCOVERY.md
+   - Summary with recommendation
+   - Findings per option
+   - Confidence level (should be MEDIUM-HIGH)
+
+Output: `.drive/phases/XX-name/DISCOVERY.md`
+</step>
+
+<step name="level_3_deep">
+**Level 3: Deep Dive (1+ hour)**
+
+For: Architectural decisions, novel problems.
+
+1. **Scope the discovery:**
+   - Define clear scope
+   - List specific questions to answer
+   - Set include/exclude boundaries
+
+2. **Exhaustive research:**
+   Use research subagents for:
+   - All relevant libraries/frameworks
+   - Architecture patterns
+   - Best practices
+   - Known limitations
+
+3. **Deep analysis:**
+   - How others solved similar problems
+   - Production experiences
+   - Gotchas and anti-patterns
+
+4. **Cross-verify ALL findings:**
+   - Every claim verified with authoritative source
+   - Mark verified vs assumed
+   - Flag contradictions
+
+5. **Create comprehensive DISCOVERY.md:**
+   - Full template structure
+   - Quality report with sources
+   - Confidence per finding
+   - Validation checkpoints if LOW confidence
+
+6. **Confidence gate:**
+   If LOW confidence on critical finding:
+   ```
+   Discovery confidence is LOW: [reason]
+
+   Options:
+   1. Dig deeper (more research)
+   2. Proceed anyway (accept uncertainty)
+   3. Pause (need to think)
+   ```
+
+Output: Comprehensive `.drive/phases/XX-name/DISCOVERY.md`
+</step>
+
+<step name="route_to_planning">
+**Complete discovery and route:**
+
+```
+════════════════════════════════════════
+DISCOVERY COMPLETE
+════════════════════════════════════════
+
+Topic: [what was discovered]
+Depth: Level [N]
+Confidence: [HIGH/MEDIUM/LOW]
+
+Recommendation: [one-liner]
+
+Output: [path to DISCOVERY.md or "verbal confirmation"]
+
+────────────────────────────────────────
+▶ NEXT: /drive:plan [phase]
+────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<success_criteria>
+**Level 1:**
+- [ ] Known approach verified
+- [ ] Verbal confirmation to proceed
+
+**Level 2:**
+- [ ] Options researched
+- [ ] Comparison made
+- [ ] DISCOVERY.md created
+- [ ] Confidence MEDIUM+
+
+**Level 3:**
+- [ ] Scope defined
+- [ ] Exhaustive research
+- [ ] All findings cross-verified
+- [ ] DISCOVERY.md created
+- [ ] Confidence gate passed
+</success_criteria>

package/modules/drive/src/workflows/discuss-milestone.md

@@ -0,0 +1,245 @@
+<purpose>
+Facilitate vision articulation before creating a milestone. Acts as a thinking partner to explore what the user wants to build, then creates MILESTONE-CONTEXT.md for handoff to create-milestone.
+
+**Philosophy:** Features first — everything else (scope, phases, constraints) derives from what the user wants to build.
+</purpose>
+
+<when_to_use>
+- User completed previous milestone, considering what's next
+- User wants to think through scope before committing
+- User has rough ideas but needs to articulate them
+- Before /drive:milestone when planning is desired
+</when_to_use>
+
+<loop_context>
+N/A - This is a pre-planning workflow, not a loop phase.
+After discussion, routes to /drive:milestone (create-milestone).
+</loop_context>
+
+<required_reading>
+@.drive/STATE.md
+@.drive/PROJECT.md (current requirements and progress)
+@.drive/MILESTONES.md (previous milestone accomplishments, if exists)
+</required_reading>
+
+<references>
+@src/templates/milestone-context.md (handoff format)
+</references>
+
+<process>
+
+<step name="check_state" priority="first">
+1. Read STATE.md for current position
+2. Read MILESTONES.md (if exists) for prior accomplishments
+
+3. **If active milestone exists:**
+   ```
+   You have an active milestone: {milestone_name}
+
+   [1] Complete current milestone first
+   [2] Start discussion for NEXT milestone (plan ahead)
+   ```
+   Wait for decision.
+
+4. **If no active milestone:**
+   - Display: "Let's define your next milestone."
+   - Proceed to milestone_context step
+</step>
+
+<step name="milestone_context">
+**Present prior accomplishments (if any):**
+
+```
+════════════════════════════════════════
+MILESTONE DISCUSSION
+════════════════════════════════════════
+
+{If MILESTONES.md exists:}
+Previous milestone: {last_milestone_name}
+Accomplishments:
+- {accomplishment_1}
+- {accomplishment_2}
+- {accomplishment_3}
+
+{If PROJECT.md has validated requirements:}
+Shipped so far:
+- {validated_requirement_1}
+- {validated_requirement_2}
+
+{If PROJECT.md has active requirements:}
+Still planned:
+- {active_requirement_1}
+- {active_requirement_2}
+
+────────────────────────────────────────
+```
+
+This gives user context for the discussion.
+</step>
+
+<step name="explore_features">
+**The core question — features first:**
+
+```
+What do you want to build next?
+
+Don't worry about phases or structure yet — just describe the features,
+capabilities, or improvements you have in mind.
+
+(Examples: "Add milestone management", "Fix auth flow and add OAuth",
+ "Build dashboard with real-time updates")
+```
+
+Wait for user response.
+
+**Follow-up if needed:**
+- "Any other features you're considering?"
+- "What's the main problem this solves?"
+- "What would 'done' look like for this?"
+
+Store responses as `features` list.
+</step>
+
+<step name="synthesize_scope">
+From the features discussed, derive:
+
+1. **Milestone name/version:**
+   - Infer from features (e.g., "Auth features" → "v0.4 Authentication")
+   - Or ask: "What would you call this milestone?"
+
+2. **Estimated phases:**
+   - Group features into logical phases
+   - Typical: 2-4 phases per milestone
+   - Ask: "Does this grouping make sense? {phase_breakdown}"
+
+3. **Constraints:**
+   - Derive from discussion
+   - Ask: "Any constraints or limitations to keep in mind?"
+
+4. **Theme (one sentence):**
+   - Synthesize: "So the focus is: {theme}. Sound right?"
+
+Confirm with user before proceeding.
+</step>
+
+<step name="write_context">
+Create `.drive/MILESTONE-CONTEXT.md`:
+
+```markdown
+# Milestone Context
+
+**Generated:** {date}
+**Status:** Ready for /drive:milestone
+
+## Features to Build
+
+{features as bullets with descriptions}
+
+## Scope
+
+**Suggested name:** {milestone_name}
+**Estimated phases:** {phase_count}
+**Focus:** {theme}
+
+## Phase Mapping
+
+| Phase | Focus | Features |
+|-------|-------|----------|
+| {next_phase} | {focus} | {features} |
+| {next_phase+1} | {focus} | {features} |
+
+## Constraints
+
+{constraints as bullets}
+
+## Additional Context
+
+{any other notes from discussion}
+
+---
+
+*This file is temporary. It will be deleted after /drive:milestone creates the milestone.*
+```
+
+Display:
+```
+Context saved to .drive/MILESTONE-CONTEXT.md
+
+This file persists across /clear so you can take a break if needed.
+```
+</step>
+
+<step name="handoff">
+Route to create-milestone:
+
+```
+════════════════════════════════════════
+DISCUSSION COMPLETE
+════════════════════════════════════════
+
+Milestone: {milestone_name}
+Features: {feature_count}
+Phases: {phase_count}
+
+Context saved for handoff.
+
+────────────────────────────────────────
+▶ NEXT: /drive:milestone
+  Create the milestone structure from this context
+────────────────────────────────────────
+
+Type "yes" to proceed, or continue discussing.
+```
+
+**Accept:** "yes", "go", "create" → run `/drive:milestone`
+</step>
+
+</process>
+
+<output>
+- .drive/MILESTONE-CONTEXT.md created (handoff file)
+- Features, scope, and phases articulated
+- Ready for /drive:milestone to consume
+</output>
+
+<success_criteria>
+- [ ] Prior accomplishments presented (if any)
+- [ ] Features explored (user-driven)
+- [ ] Scope synthesized from features
+- [ ] Phase mapping suggested
+- [ ] MILESTONE-CONTEXT.md written
+- [ ] Clear handoff to /drive:milestone
+</success_criteria>
+
+<anti_patterns>
+**Asking abstract questions first:**
+DON'T: "What's the scope of the next milestone?"
+DO: "What do you want to build?"
+
+**Assuming phases before features:**
+DON'T: "How many phases do you want?"
+DO: Derive phases from the features discussed.
+
+**Skipping confirmation:**
+DON'T: Write context immediately after one question.
+DO: Confirm the synthesis makes sense before writing.
+
+**Not persisting context:**
+DON'T: End discussion without writing MILESTONE-CONTEXT.md
+DO: Always write the file so /clear doesn't lose progress.
+</anti_patterns>
+
+<error_handling>
+**User unsure what to build:**
+- Reference PROJECT.md active requirements
+- Suggest: "What's the most painful thing right now?"
+- Offer: "We can start with one feature and expand"
+
+**Scope too large:**
+- Suggest splitting: "That sounds like 2-3 milestones"
+- Ask: "What's the minimum viable version?"
+
+**User wants to skip discussion:**
+- Route directly to /drive:milestone
+- Note: "Going straight to milestone creation — no discussion context will be available"
+</error_handling>