Skip to content

Example Issue-to-PR Flow (Worked Flows)

Four worked examples that trace a piece of work end to end — from first idea to merged pull request — across mobile, desktop, cloud agents, the CLI, and external AI tools. Use them as concrete reference flows when you are unsure how a handoff should look. New to the project? See How Brain Factory works first.

Shared rule for all examples

GitHub is the single source of record. If context starts somewhere else (local notes, Google Drive, OneDrive, connector-accessed files, or external AI output), turn it into GitHub artifacts — an issue, discussion, or ADR — before implementation starts. The docs call this "normalizing" the context.

Example 1: Feature delivery flow (idea → issue → plan → implement → review → merge → follow-up)

Scenario

A team wants to add a "CSV export by date range" feature.

  1. Idea capture (GitHub Mobile)
  2. PM opens an Enhancement issue from mobile.
  3. Adds objective, user impact, constraints, and acceptance criteria.
  4. Planning (GitHub Copilot Chat on github.com)
  5. Maintainer asks Copilot Chat to draft implementation plan from issue.
  6. Plan is pasted back into issue comments; constraints are refined.
  7. Implementation (choose one surface)
  8. Path A: Engineer uses VS Code Copilot (local) for coding/debugging.
  9. Path B: Maintainer uses GitHub Copilot Coding Agent for bounded repo task.
  10. PR creation
  11. PR links issue (Closes #123) and states execution surface.
  12. PR includes validation evidence and non-goals.
  13. Review + approval (desktop + mobile)
  14. Reviewer checks acceptance criteria and constraint preservation.
  15. Approver gives final approval from mobile.
  16. Merge + follow-up
  17. Branch deleted.
  18. Any deferred edge-case work is captured as an Improvement issue.

Example 2: Support-to-product improvement flow (support ticket → triage → enhancement/ADR → implementation → release → closure)

Scenario (support-to-product)

Support reports repeated confusion in onboarding email copy.

  1. Support intake
  2. Support lead creates Support Intake issue with severity and customer impact.
  3. Triage (GH CLI + project routing)
  4. Labels: support, triage, severity.
  5. Project status set to Triage, owner assigned.
  6. Status update is backed by durable issue comments/links, not chat-only notes.
  7. Conversion
  8. Triage determines it is product + docs work.
  9. Linked Enhancement issue created for behavior change.
  10. Linked Docs issue created for user-facing wording updates.
  11. Decision checkpoint (ADR if needed)
  12. If changing onboarding policy, create ADR Proposal issue first.
  13. Implementation + release
  14. Coding agent or local VS Code Copilot executes enhancement issue.
  15. Docs issue completed in parallel or same PR when tightly coupled.
  16. Loop closure
  17. PR merged and linked issues closed.
  18. Support issue updated with release note and communication sent.
  19. Recurring pattern logged as Improvement item for future prevention.

Example 3: Redevelopment/discovery flow (discovery issue → ADR → phased implementation issues → project tracking)

Scenario (redevelopment/discovery)

Legacy reporting workflow needs modernization.

  1. Discovery intake
  2. Create Redevelopment/Discovery issue with source material references.
  3. External synthesis
  4. External AI agent summarizes legacy docs and interviews.
  5. Output is normalized into issue + discussion with assumptions/questions.
  6. ADR proposal
  7. Team creates ADR Proposal issue for target architecture decision.
  8. Phased decomposition
  9. Create phased issues: data model migration, API compatibility, UI transition.
  10. Add all to GitHub Project with status and dependency fields.
  11. Phased implementation
  12. Each phase executes on separate branch/PR with explicit validation gates.
  13. Governed closure
  14. ADR accepted/superseded status updated.
  15. Project view confirms all phases complete and follow-up debt captured.

Example 4: Mobile follow-up flow (mobile signal → handoff → completion)

Scenario (mobile follow-up)

Approver on mobile notices PR lacks constraint reference.

  1. Approver leaves mobile comment requesting missing constraint traceability.
  2. Approver opens a linked Improvement issue from mobile.
  3. Assignee picks issue on desktop and updates PR description + docs.
  4. Reviewer confirms governance checklist items are now complete.
  5. Approval is granted on mobile, PR merges, branch deletes.
  6. Follow-up issue closes with note: "constraint traceability pattern added to template."

Why these examples matter

These flows make handoffs explicit, keep constraints durable, and stop implementation from starting on context that has not yet been normalized into GitHub.

Mobile quick action

  • Use when: you need a fast, concrete flow reference from mobile to unblock routing or review.
  • Do from mobile:
  • Pick the closest worked example and cite it in the active issue or PR comment.
  • Confirm the current stage ordering and capture any missing step as a follow-up.
  • Update project status/owner fields to match the selected flow.
  • Do not do from mobile:
  • Treat an example as a full implementation spec for complex edge cases.
  • Rewrite multi-stage flow definitions from phone.
  • Escalate to desktop/cloud when:
  • Real-world workflow deviates materially and needs a new or revised worked example.
  • Validation evidence is missing across multiple lifecycle stages.
  • Primary artifact to update:
  • The issue or pull request comment documenting which example flow is being followed.