Skip to content

issue-to-impl.md

Latest commit

 

History

History
77 lines (59 loc) · 2.72 KB

issue-to-impl.md

File metadata and controls

77 lines (59 loc) · 2.72 KB

Issue to Implementation Workflow

Complete development cycle from GitHub issue to pull request.

graph TD
    A[Github Issue created] --> B[Fork new branch from main]
    B --> C[Step 5: Update documentation]
    C --> C2[Create docs commit with tag]
    C2 --> D[Step 6: Create/update test cases]
    D --> E[Step 8: towards-next-milestone skill]
    E -->|more than 800 lines w/o finishing| F[Create milestone document]
    F --> G[User starts next session]
    G --> E
    E -->|finish all tests| H[Code reviewer reviews quality]
    H --> H2[Code simplifier checks simplicity]
    H2 -->|simplification needed| E
    H2 -->|code is simple enough| I[Create pull request]
    I --> J[User reviews and merges]

    style G fill:#ffcccc
    style J fill:#ffcccc
    style B fill:#ccddff
    style C fill:#ccddff
    style C2 fill:#ccddff
    style D fill:#ccddff
    style E fill:#ccddff
    style F fill:#ccddff
    style H fill:#ccddff
    style I fill:#ccddff
Loading

Documentation Commit Convention

The workflow creates a dedicated [docs] commit during Step 5, separate from test and implementation commits:

  1. Documentation files updated - apply changes from "Documentation Planning" section
  2. Diff specifications followed - if plan includes --diff previews, apply them directly
  3. Separate commit created - [docs] tag enables easy tracking and revert if needed

This separation provides:

  • Clear audit trail for documentation changes
  • Ability to revert documentation independently from code
  • Explicit tracking of documentation completeness

Plan Caching

During Step 4 (Read Implementation Plan), the workflow extracts the "Proposed Solution" section from the GitHub issue and caches it locally:

Cache location: ${AGENTIZE_HOME:-.}/.tmp/plan-of-issue-{N}.md

This cached plan enables:

  • Drift awareness during handsoff continuation prompts
  • Easier resumption when sessions are interrupted
  • Context preservation across multiple continuation cycles

The stop hook reads this cached plan (when available) and includes it in the /issue-to-impl continuation prompt. If the plan cache is missing, the continuation prompt gracefully degrades without the plan context.

Dry-Run Mode

Use --dry-run to preview the implementation workflow without making changes:

/issue-to-impl 42 --dry-run

Behavior:

  • Reads the issue plan and validates it has a "Proposed Solution" section
  • Prints a preview of intended actions:
    • Branch that would be created
    • Files that would be modified/created
    • Estimated LOC per step
    • Test strategy summary
  • Does NOT: Create branch, modify files, create commits, write milestone files, or create PR

Use case: Verify the issue has a complete plan before starting implementation.