issue-workflow

Issue Workflow

Issue Lifecycle

Every issue moves through four states on the project board:

Todo  -->  In Progress  -->  Review  -->  Done

State	Meaning
Todo	Accepted and ready for development
In Progress	Actively being worked on by an assigned developer
Review	Pull request submitted, awaiting review
Done	Merged and closed

State Transition Rules

• Move to In Progress only when actively starting work. Do not claim issues speculatively.
• Move to Review when the pull request is submitted, not before.
• Move to Done automatically when the PR merges and the issue closes via Closes #ID.

---

Development Flow

Follow this sequence for every issue, from selection through merge.

Step 1: Select an Issue

• Pick an issue from the Todo column.
• Prioritize issues that are well-defined with clear acceptance criteria.
• Check for dependencies on other issues before starting.

Step 2: Assign and Claim

• Self-assign the issue on GitHub.
• Move the issue to In Progress on the project board.
• Communicate intent if working in a team context.

Step 3: Create a Branch

• Pull latest from origin/main.
• Create a branch following naming conventions: <prefix>/<issue-id>-<short-description>.

git fetch origin
git checkout -b feature/42-add-user-auth origin/main

Step 4: Implement with TDD

• Follow the TDD Red-Green-Refactor cycle for all implementation work.
• Write a failing test first, then make it pass, then refactor.
• Commit frequently with conventional commit messages.
• Reference the issue number in commit scopes where relevant.

Step 5: Submit Pull Request

• Push the branch to the remote.
• Create a pull request following PR conventions (see below).
• Move the issue to Review on the project board.

Step 6: Address Review Feedback

• Respond to all review findings.
• Fix Critical and Important findings. Discuss Suggestions.
• Push additional commits to the same branch.
• Re-request review after addressing feedback.

Step 7: Merge

• Use squash and merge to collapse all branch commits into one clean commit.
• The branch is deleted after merge.
• The issue auto-closes via the Closes #ID reference in the PR body.

---

Pull Request Conventions

PR Title Format

<type>: #<ID> <description>

Examples:

feat: #42 add JWT authentication
fix: #87 resolve date parser null error
docs: #15 update API reference for v2 endpoints

PR Body Template

Structure every PR body with these sections:

Closes #<issue-id>

## Summary

Brief description of what this PR accomplishes and why.

- Key change 1
- Key change 2
- Key change 3

## Test Plan

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Edge cases covered
- [ ] Manual verification of acceptance criteria

PR Rules

• Reference the issue with Closes #<issue-id> to enable auto-closing on merge.
• Keep PRs focused. One issue per PR unless issues are tightly coupled.
• Include a summary that explains the "why", not just the "what".
• Provide a concrete test plan with checkboxes.

---

Review Process

Review Layers

1. Automated/AI Review: Runs automatically on PR creation. Checks code quality, patterns, and potential issues.
2. Human Review: Manual review by a team member. Focuses on architecture, business logic, and maintainability.

Finding Categories

Category	Severity	Action Required
Critical	High	Must fix before merge
Important	Medium	Should fix before merge
Suggestion	Low	Optional improvement

Responding to Findings

• Address all Critical findings. These block the merge.
• Address Important findings unless a compelling reason exists to defer (document why).
• Consider Suggestions as improvements. Implement if straightforward, otherwise note for future work.
• Never dismiss findings without explanation.

---

Merge Strategy

Squash and Merge

All PRs merge using squash and merge. This means:

• All commits on the feature branch collapse into a single commit on main.
• The commit message on main reflects the PR title and description.
• The feature branch is deleted after merge.
• The linked issue auto-closes via the Closes #ID reference.

Why Squash Merge

• Keep main history clean and readable.
• Each commit on main represents one complete, reviewed feature or fix.
• Simplify rollbacks: revert one commit to undo an entire feature.

---

Resuming Work

When returning to an issue after a break or context switch, follow these steps to re-orient.

Step 1: Check for Existing Branch

git branch -a | grep <issue-id>

If a branch exists, check it out. If not, determine whether work was already started by someone else.

Step 2: Check PR Status

gh pr list --search "<issue-id>"

Look for open, closed, or draft PRs related to the issue. Read any existing review comments.

Step 3: Review Previous Commits

git log --oneline origin/main..<branch-name>

Understand what has already been done. Read the diff to restore context.

Step 4: Continue from Last State

• If tests are failing, start there. Fix failing tests before adding new work.
• If all tests pass, identify the next acceptance criterion and write the next failing test.
• If the PR exists and has review comments, address those first.

---

Quick Reference

Action	Command / Convention
Create branch	git checkout -b feature/ID-desc origin/main
PR title	<type>: #<ID> <description>
Auto-close issue	Closes #<ID> in PR body
Merge strategy	Squash and merge
Post-merge cleanup	Branch auto-deleted
Issue states	Todo > In Progress > Review > Done

---

Dependencies

Skill	Reason
dev-conventions	Branch naming, commit format, label system, and merge strategy are defined there
tdd-discipline	Step 4 mandates the TDD Red-Green-Refactor cycle for all implementation

Used By

Component	Reason
Command: create-issue	Creates structured issues following the issue templates
Command: pick-issue	Claims issues and creates branches per this workflow
Command: develop	Orchestrates the full lifecycle defined here
Command: submit-pr	Creates PRs following the PR conventions