Drive Workflow

Drive Workflow

Step-by-step workflow for implementing a single ticket during /​drive.

Steps

1. Read and Understand the Ticket

• Read the ticket file to understand requirements
• Identify key files mentioned in the ticket
• Understand the implementation steps outlined

2. Implement the Ticket

• Follow the implementation steps in the ticket
• Use existing patterns and conventions in the codebase
• Run type checks (per CLAUDE.md) to verify changes
• Fix any type errors or test failures before proceeding

3. Ask User to Review Implementation

STOP and ask the user to review the implementation before proceeding.

Show ticket context to help user understand what they're reviewing:

• Display the ticket title (H1 heading from ticket file)
• Include a brief summary (first 1-2 sentences from Overview section)
• Show a summary of changes made

Use AskUserQuestion tool to confirm:

• "Approve" - implementation is correct, proceed to commit and continue to next ticket
• "Approve and stop" - implementation is correct, commit this ticket but stop driving
• "Abandon" - write failure analysis, discard changes, and continue to next ticket

Do NOT proceed to commit until user explicitly approves.

Approval Prompt Format

**Ticket: <Title from H1>**
<Summary from Overview section - first 1-2 sentences>

Implementation complete. Changes made:
- <Change 1>
- <Change 2>

Do you approve this implementation?
[Approve / Approve and stop / Abandon]

4. Update Effort and Write Final Report

After user approves:

1. Update the effort field in the ticket's YAML frontmatter with actual time spent in numeric hours. Valid values: 0.1h, 0.25h, 0.5h, 1h, 2h, 4h. Do NOT use t-shirt sizes (XS, S, M) or minutes (10m). Estimate based on implementation complexity.

2. Append a "## Final Report" section to the ticket file.

If no insights discovered:

## Final Report

Development completed as planned.

If meaningful insights were discovered during implementation:

Add a "### Discovered Insights" subsection capturing learnings that help future developers understand the codebase:

## Final Report

Development completed as planned.

### Discovered Insights

- **Insight**: <what was discovered>
  **Context**: <why this matters for understanding the codebase>

What Makes a Good Insight

Include insights that fall into these categories:

• Architectural patterns: Hidden design decisions or conventions not documented elsewhere
• Code relationships: Non-obvious dependencies or coupling between components
• Historical context: Why something exists in its current form (discovered via git blame or comments)
• Edge cases: Gotchas or surprising behaviors that future developers should know

Insight Guidelines

• Keep insights actionable and specific, not vague observations
• Insights should benefit someone reading the ticket months later
• Don't duplicate information already in the ticket's Overview or Implementation Steps
• If no meaningful insights were discovered, omit the subsection entirely

This creates a historical record of decisions and discoveries made during implementation.

5. Commit and Archive Using Skill

After writing the final report, run the archive-ticket skill which handles everything:

bash .claude/​skills/​archive-ticket/​sh/​archive.sh \
  <ticket-path> \
  "<commit-message>" \
  <repo-url> \
  "<description>" \
  [modified-files...]

CRITICAL: The archive script is the ONLY way to archive tickets. It handles everything automatically.

Prohibited Actions

NEVER do any of the following:

• NEVER use mv or git mv to move ticket files
• NEVER create directories like done/, completed/, finished/, or any custom archive location
• NEVER manually update CHANGELOG files
• NEVER manually set commit_hash or category frontmatter fields

The ONLY valid archive location is .workaholic/​tickets/​archive/<branch>/. The script determines the branch name and creates the directory. Any manual file operations will result in incorrect archive structure.

Note: The archive script uses git add -A, which includes:

• All implementation changes
• The archived ticket file
• Any uncommitted ticket files in .workaholic/​tickets/​todo/
• CHANGELOG updates

This means newly created tickets are automatically included in drive commits.

After Committing

• If user selected "Approve": automatically proceed to the next ticket without asking for confirmation
• If user selected "Approve and stop": stop driving and report how many tickets remain (e.g., "Stopped. 2 tickets remaining in queue.")

If User Selects "Abandon"

When the user selects "Abandon", do NOT commit implementation changes. Instead:

1. Discard implementation changes: Run git restore . to revert all uncommitted changes

2. Append Failure Analysis section to the ticket file:

   ## Failure Analysis
   
   ### What Was Attempted
   - <Brief description of the implementation approach>
   
   ### Why It Failed
   - <Reason the implementation didn't work or was abandoned>
   
   ### Insights for Future Attempts
   - <Learnings that could help if this is reattempted>
   

3. Move ticket to fail directory:

   mkdir -p .workaholic/​tickets/​fail
   mv <ticket-path> .workaholic/​tickets/​fail/
   

4. Commit the ticket move to preserve the failure analysis in git history:

   git add .workaholic/​tickets/
   git commit -m "Abandon: <ticket-title>"
   

5. Continue to next ticket without asking for confirmation

This allows users to abandon a failed implementation attempt while preserving insights from the attempt for future reference.

Commit Message Rules

• NO prefixes (no [feat], fix:, etc.)
• Start with present-tense verb (Add, Update, Fix, Remove, Refactor)
• Focus on WHAT changed in the title
• Keep title concise (50 chars or less)

Description Rules

• 1-2 sentences explaining the motivation behind the change
• Capture the "why" from the ticket's Overview section
• This appears in CHANGELOG and helps generate meaningful PR descriptions