User Input → Context Detection
    ↓
Checkpoint 1: Understanding the Problem (WAIT)
    ↓
Checkpoint 2: Issue Details (WAIT)
    ↓
Checkpoint 3: Implementation Guidance (WAIT)
    ↓
Checkpoint 4: Acceptance & Testing (WAIT)
    ↓
Checkpoint 5: Labels & Priority (WAIT)
    ↓
Checkpoint 6: Final Review (WAIT)
    ↓
GitHub CLI Commands

Issue Creation: [Type]

CHECKPOINT 1: Understanding the Problem
─────────────────────────────────────────

Let me make sure I understand:

Type: [Bug/Enhancement/Technical Debt/Testing/Documentation]
Scope: [UI/UX/Model/Architecture/Testing/Performance]
Affected area: [Specific component/screen/service]
Priority: [P0-Critical/P1-High/P2-Medium/P3-Low] (preliminary)

Specifics:
- [Key detail 1]
- [Key detail 2]
- [Impact statement]

Is this correct? Any other details I should know? (y/n/more details)

─────────────────────────────────────────
CHECKPOINT 2: Issue Details

Title: "[type]: [brief description in lowercase]"

Context:
[Why this matters, background, when/where discovered]

Current Behavior:
[What happens now - for bugs: steps to reproduce]

Expected Behavior:
[What should happen instead]

Does this capture the issue correctly? Any adjustments needed? (y/n/edit)

─────────────────────────────────────────
CHECKPOINT 3: Implementation Guidance

Proposed Solution:
[High-level approach if clear, or "To be determined during implementation"]

Tasks:
- [ ] [Task 1 - typically: Analyze/Design/Implement/Test]
- [ ] [Task 2]
- [ ] [Task 3]
- [ ] [Consider localization if UI changes]
- [ ] [Run flutter analyze && flutter test]

Technical Notes:
- Affected files: [list specific files if known]
- Related issues: #XXX [if applicable]
- Pattern to follow: [reference similar work]
- Database changes: [if applicable]
- [Other technical context]

Is this implementation direction helpful? (y/n/adjust)

─────────────────────────────────────────
CHECKPOINT 4: Acceptance & Testing

Acceptance Criteria:
- [ ] [Criterion 1 - core functionality works]
- [ ] [Criterion 2 - edge cases handled]
- [ ] [Criterion 3 - tests pass]
- [ ] [Criterion 4 - no regressions]
- [ ] [Localized in EN and PT-BR] (if UI)

Test Cases:
- [Main workflow test]
- [Edge case 1]
- [Edge case 2]
- [Error scenario test]

Are these acceptance criteria complete? Need more? (y/n/add)

─────────────────────────────────────────
CHECKPOINT 5: Labels & Priority

Recommended labels:
- Type: [enhancement/bug/technical-debt/testing/documentation]
- Scope: [UI/UX/model/architecture/testing/performance/i18n]
- Priority: [P0-Critical/P1-High/P2-Medium/P3-Low]
- Additional: [good first issue] (if applicable)

Priority reasoning:
[Why this priority level - impact, urgency, blocking other work]

Story Point Estimate: [X points] (preliminary)
Estimation reasoning:
- Complexity: [simple/moderate/complex]
- Files affected: [few/several/many]
- Testing required: [minimal/moderate/comprehensive]
- Uncertainty: [low/medium/high]
- Estimated effort: [X-Y hours]

Agree with labels and estimate? (y/n/adjust)

─────────────────────────────────────────
CHECKPOINT 6: Final Review

Here's the complete issue:

─────────────────────────────────────────
[Display complete issue markdown]
─────────────────────────────────────────

Ready to create this issue? (y/n/revise)

If "revise": Which section? (1-5 to go back to checkpoint)
If "y": [Proceed to GitHub CLI commands]

# Create the issue
gh issue create \
  --title "[type]: [description]" \
  --body "$(cat <<'EOF'
[Complete issue markdown]
EOF
)"

# This will return an issue number, e.g., #267

# Add labels
gh issue edit 267 --add-label "label1,label2,label3"

# Optional: Add to project (can be done during sprint planning)
gh project item-add 3 --owner alemdisso \
  --url https://github.com/alemdisso/gastrobrain/issues/267

# Optional: Set milestone (if known)
gh issue edit 267 --milestone "0.2.0 - Beta-Ready Phase"

## Context
[When/where discovered, impact on users, severity justification]

## Current Behavior

**Steps to Reproduce:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Actual Result:** [What happens - be specific]

**Expected Result:** [What should happen]

[Optional: Screenshots, error messages, logs]

## Proposed Solution
[How to fix if known, or "To be investigated during implementation"]

## Tasks
- [ ] Reproduce bug with test case
- [ ] Identify root cause in [affected component]
- [ ] Implement fix
- [ ] Add regression test
- [ ] Verify fix works across scenarios
- [ ] Run flutter analyze && flutter test

## Acceptance Criteria
- [ ] Bug no longer occurs with reproduction steps
- [ ] Regression test added to prevent recurrence
- [ ] No new bugs introduced
- [ ] Related functionality still works correctly
- [ ] All existing tests pass

## Technical Notes
- **Affected files:** [list paths]
- **Discovered in:** #XXX [if during other work]
- **Suspected cause:** [hypothesis if known]
- **Related issues:** #XXX [if applicable]
- **Testing pattern:** [reference applicable guide]

## Test Cases
- Test that reproduces the bug
- Test that verifies the fix
- Edge cases: [list scenarios]
- Regression check: [related functionality]

## Context
[Why is this needed? User pain point, opportunity, or improvement rationale]

## Current Behavior
[What exists now, what's missing, or what's suboptimal]

## Expected Behavior
[Detailed description of desired feature/improvement]
[Optional: UI mockups, workflow diagrams]

## Proposed Solution
[High-level implementation approach]
[Alternative approaches considered]

## Tasks
- [ ] Design implementation approach
- [ ] Update data models (if needed)
- [ ] Add database migrations (if needed)
- [ ] Implement core functionality
- [ ] Add UI components (if applicable)
- [ ] Add strings to app_en.arb and app_pt.arb
- [ ] Run flutter gen-l10n (if strings added)
- [ ] Write unit tests
- [ ] Write widget tests (if UI)
- [ ] Write integration/E2E tests (if workflow)
- [ ] Update documentation
- [ ] Run flutter analyze && flutter test

## Acceptance Criteria
- [ ] Feature works as specified
- [ ] Localized in both English and Portuguese
- [ ] Tests cover main scenarios and edge cases
- [ ] No regressions in existing features
- [ ] Performance is acceptable
- [ ] Follows project architecture patterns
- [ ] Documentation updated

## Technical Notes
- **New models/services:** [list if applicable]
- **Database changes:** [describe schema changes, migration needed]
- **Affected screens:** [list UI components]
- **Similar pattern:** #XXX [reference if similar work exists]
- **Dependencies:** [new packages needed]
- **Localization:** [specific strings needed]
- **Testing approach:** [reference DIALOG_TESTING_GUIDE or EDGE_CASE_TESTING_GUIDE]

## Test Cases
- Main workflow test: [describe]
- Edge cases: [list scenarios]
- Error scenarios: [list error handling]
- Empty state: [if applicable]
- Boundary conditions: [if applicable]

## Context
[Why this technical debt exists, how it impacts development/maintenance]

## Current Behavior
[Description of problematic implementation, code smell, or architectural issue]
[Examples of where the problem manifests]

## Expected Behavior
[What the improved structure/implementation should look like]
[Benefits of refactoring]

## Proposed Solution
[Refactoring approach: extract service, consolidate logic, improve pattern, etc.]
[Step-by-step approach if complex]

## Tasks
- [ ] Analyze current implementation thoroughly
- [ ] Design refactored structure
- [ ] Create new abstraction/service (if needed)
- [ ] Extract/consolidate code
- [ ] Update all call sites
- [ ] Verify all existing tests still pass
- [ ] Add tests for refactored code (if coverage gaps)
- [ ] Update documentation
- [ ] Run flutter analyze && flutter test

## Acceptance Criteria
- [ ] Code is more maintainable/readable
- [ ] All existing tests still pass
- [ ] No functionality changes (pure refactoring)
- [ ] Test coverage maintained or improved
- [ ] Related code follows new pattern
- [ ] Documentation reflects new structure

## Technical Notes
- **Files to refactor:** [list paths]
- **Pattern to follow:** [reference existing pattern or issue]
- **Similar refactoring:** #XXX [if applicable]
- **Benefits:**
  - [Reduced duplication]
  - [Clearer separation of concerns]
  - [Easier testing]
  - [Other benefits]
- **Risks:** [potential issues during refactoring]

## Test Cases
- Verify existing behavior is unchanged
- Test all affected code paths
- Edge cases still handled correctly
- No regressions in dependent code

## Context
[Why these tests are needed, what coverage gap exists]

## Current Behavior
[Current test coverage state, what's missing]

## Expected Behavior
[Desired test coverage level, scenarios that should be tested]

## Proposed Solution
[Testing approach, which test helpers to use]

## Tasks
- [ ] Identify test scenarios (happy path, edge cases, errors)
- [ ] Set up test fixtures/mocks
- [ ] Write unit tests (if applicable)
- [ ] Write widget tests (if UI)
- [ ] Write integration tests (if workflow)
- [ ] Test edge cases (empty states, boundary conditions)
- [ ] Test error scenarios
- [ ] Verify coverage improvement
- [ ] Run flutter test --coverage && flutter analyze

## Acceptance Criteria
- [ ] All identified scenarios have test coverage
- [ ] Tests follow project patterns (MockDatabaseHelper, TestSetup, etc.)
- [ ] Edge cases covered (see EDGE_CASE_TESTING_GUIDE.md)
- [ ] Error scenarios tested
- [ ] All tests pass consistently
- [ ] Coverage improved by [X]%

## Technical Notes
- **Component under test:** [path to file]
- **Testing pattern:** [reference DIALOG_TESTING_GUIDE, EDGE_CASE_TESTING_GUIDE, etc.]
- **Test helpers:** [MockDatabaseHelper, DialogTestHelpers, EdgeCaseTestHelpers, etc.]
- **Coverage before:** [X]%
- **Coverage target:** [Y]%

## Test Cases
- Happy path: [main workflow]
- Edge cases: [empty state, boundary conditions]
- Error scenarios: [database errors, validation failures]
- Cancellation: [if dialog]
- Alternative dismissal: [back button, tap outside, etc.]

# Search by component name
gh issue list --search "MealRecordingDialog" --state all

# Search by keyword
gh issue list --search "side dish" --state all

# Search by label
gh issue list --label "UI" --state open

Related Issues Detected:
- #237: "Consolidate MealEditService" (same service)
- #206: "Fix protein counting" (similar functionality)
- #250: "Save button obscured" (same screen)

Should I reference these in the new issue? (y/n/which ones)

Detecting active work context...
- Current branch: feature/250-save-button-fix
- Working on: Issue #250
- Current milestone: 0.1.6

Context detected:
- Discovered while working on #250
- May be related to current work
- Could block #250 completion

Should I:
1. Reference #250 in the new issue
2. Note this was discovered during #250 work
3. Consider priority relative to #250
4. Check if this blocks #250

How should we handle the relationship? (1/2/3/4/all)

"The thing where you add ingredients is super broken when you have
like a ton of them. I can't even see the save button lol"

CHECKPOINT 1: Understanding the Problem
─────────────────────────────────────────

Let me translate this to structured format:

Type: Bug
Scope: UI (layout/scrolling issue)
Affected area: Add Ingredient Dialog
Priority: P1-High (blocks core functionality)

Specifics:
- Happens when: Many ingredients in the list
- Condition: Long ingredient list
- Result: Save button not visible/accessible
- Impact: Users cannot save after selecting ingredient

My interpretation:
- Dialog doesn't scroll properly with long lists
- Save button at bottom is obscured
- Possibly viewport/layout constraint issue

Is this correct? Did I capture the issue? (y/n/more details)

"Can we make meal planning easier somehow?"

CHECKPOINT 1: Understanding the Problem
─────────────────────────────────────────

I need more details to create a good issue. Let me ask:

1. What part of meal planning is difficult?
   - Finding recipes?
   - Adding recipes to the plan?
   - Managing the weekly view?
   - Something else?

2. What would make it easier?
   - Faster workflow?
   - Less clicks?
   - Better recommendations?
   - Different UI?

3. Can you describe the current workflow that's hard?
   - Step 1: I do...
   - Step 2: Then I...
   - The hard part is...

Please provide more specifics so I can create a focused, actionable issue.

"When I edit meals, the side dishes disappear AND the date picker
shows future dates which shouldn't be allowed."

I detected TWO distinct issues in your report:

Issue A: Side dishes disappear when editing meals
- Type: Bug (data loss)
- Priority: P1-High

Issue B: Date picker allows future dates
- Type: Bug (validation)
- Priority: P2-Medium

These should be separate issues for better tracking.

Which would you like to create first? (A/B/both separately)

# Create issue with title and body
gh issue create \
  --title "bug: side dishes disappear when editing meals" \
  --body "$(cat <<'EOF'
[Issue markdown here]
EOF
)"

# Add labels to issue (use issue number from creation)
gh issue edit 267 --add-label "bug,UI,P1-High"

# Add issue to GitHub Project
gh project item-add 3 \
  --owner alemdisso \
  --url https://github.com/alemdisso/gastrobrain/issues/267

# Assign to milestone
gh issue edit 267 --milestone "0.1.6 - Shopping List & Polish"

# List available milestones
gh api repos/:owner/:repo/milestones --jq '.[] | {number, title}'

# Assign to yourself (solo dev)
gh issue edit 267 --add-assignee @me

# Reference in comment (for relationships)
gh issue comment 267 --body "Related to #250 - discovered during that work"
gh issue comment 267 --body "Blocks #250 - must fix before completing"
gh issue comment 267 --body "Duplicate of #123 - closing this one"