Problem
Two related gaps in the AI dev workflow:
-
The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) runs entirely inside one ephemeral chat session. Research, terminology decisions, ADRs, and the PRD live only in that conversation until issues get filed directly from chat. There is no review gate before implementation issues spawn, and the reasoning is not captured as durable, reviewable git history.
-
The workflow has no first-class notion of a ticket whose subject is the AI dev workflow itself. This very ticket is one — a change to how we research and author work. The new ai-workflow label marks that category.
Proposed pipeline
Turn the research flow into a branch-based pipeline gated by PR review:
-
Initial research ticket — a human files a lightweight ticket describing what is being researched / triaged (the question, not the answer). This is the entry point and the thing the branch is named for.
-
Grilling session on a branch — the grill-with-docs (and to-prd) session runs against that ticket. All artifacts it produces — CONTEXT.md edits, new ADRs, the PRD doc — are committed to a dedicated branch tied to the initial ticket, instead of living only in chat.
-
Push + review — the branch is pushed and opened as a draft PR against develop. Humans review the research, terminology, ADRs, and PRD before any implementation work is broken out.
-
Merge to auto-create implementation tickets — once the PR merges, the to-issues breakdown is generated automatically as GitHub issues linked back to the initial ticket. Out of scope here; tracked in a separate follow-up PR.
Explicit support for AI-dev-workflow tickets
Make "change to the AI dev workflow" a recognized ticket category:
- The ai-workflow label marks these tickets.
- Guidance in docs/agents for when a ticket targets the workflow itself (the .claude skills and docs/agents) vs the product (angular-client / scylla-server).
- This ticket is the prototype instance — it should fit the category it defines.
Scope of this ticket
- Define and document the pipeline (stages 1 through 3) in docs/agents and a new ADR.
- Establish the AI-dev-workflow ticket category: document the ai-workflow label in the label palette + docs/agents guidance.
- Adjust the grill-with-docs / to-prd skills (or add guidance) so a session's output is committed to a research branch tied to the initial ticket, rather than only filing issues from chat.
- Decide where the PRD lives as a committed artifact (e.g. under docs/) so it is reviewable in the PR diff.
- Establish the initial-research-ticket convention: label, title shape, and branch naming.
Out of scope / follow-up
- Stage 4 automation: auto-creating the implementation issues on merge (GitHub Action or merge hook that runs to-issues). Separate follow-up PR.
Open questions
- Where does the committed PRD live, and does it stay in-repo after issues are created or get pruned?
- How does merge trigger to-issues in stage 4 — an Action on merge to develop, keyed off the PRD file path?
Problem
Two related gaps in the AI dev workflow:
The AI issue-authoring flow (grill-with-docs to-prd to-issues triage) runs entirely inside one ephemeral chat session. Research, terminology decisions, ADRs, and the PRD live only in that conversation until issues get filed directly from chat. There is no review gate before implementation issues spawn, and the reasoning is not captured as durable, reviewable git history.
The workflow has no first-class notion of a ticket whose subject is the AI dev workflow itself. This very ticket is one — a change to how we research and author work. The new ai-workflow label marks that category.
Proposed pipeline
Turn the research flow into a branch-based pipeline gated by PR review:
Initial research ticket — a human files a lightweight ticket describing what is being researched / triaged (the question, not the answer). This is the entry point and the thing the branch is named for.
Grilling session on a branch — the grill-with-docs (and to-prd) session runs against that ticket. All artifacts it produces — CONTEXT.md edits, new ADRs, the PRD doc — are committed to a dedicated branch tied to the initial ticket, instead of living only in chat.
Push + review — the branch is pushed and opened as a draft PR against develop. Humans review the research, terminology, ADRs, and PRD before any implementation work is broken out.
Merge to auto-create implementation tickets — once the PR merges, the to-issues breakdown is generated automatically as GitHub issues linked back to the initial ticket. Out of scope here; tracked in a separate follow-up PR.
Explicit support for AI-dev-workflow tickets
Make "change to the AI dev workflow" a recognized ticket category:
Scope of this ticket
Out of scope / follow-up
Open questions