PRD: Agentic Workflow#67
Draft
roberthunterjr wants to merge 10 commits into
Draft
Conversation
roberthunterjr
marked this pull request as draft
July 2, 2026 17:00
Define a full Jira-ready bug workflow with readiness checks, feasibility scoring, fail-first tests, intent alignment loops, scoped refactor rules, and final verification gates. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Transform placeholder notes and design thoughts into proper JTBD statements, functional requirements, NFRs, out-of-scope items, open questions, development phases, and a glossary. All major sections are now populated with content derived from a structured interview.
Add platform framing, Agentic Loop Engineering rationale (recursion analogy), meta-harness and factory operator concepts, ADLC as a cross-workflow sequence, observability and governance requirements, JTBD-OBS and JTBD-FEEDBACK, FR-CROSS-7 through FR-CROSS-10, NFR-3/4, and an expanded glossary.
… metrics to PRD Add Section 1.2 User Roles with Phase 0 persona definitions. Add FR-CROSS-11 through FR-CROSS-14 covering branch scoping, credential management, prompt injection defense, and protected file scoping. Add Section 3.3 Agent-Jira Contract (FR-JIRA-1 through FR-JIRA-7) and Section 3.4 Agent-GitHub Contract (FR-GH-1 through FR-GH-5). Add Section 3.5 Failure Modes (FR-FAIL-1 through FR-FAIL-6) covering token limits, pre-check retries, concurrency, Dependabot revert, and API failure backoff. Add Section 8 Success Metrics for Phase 0 and Phase 1. Add TOC, RFC 2119 note, and expanded glossary.
Add three Mermaid diagrams: - System context pipeline (Section 2): two-pipeline overview showing Phase 0 Jira flow and Phase 1 community GitHub Issue flow - ADLC flowchart (Section 3.2): 8-step governed loop with readiness check failure exit, pre-check retry path, escalation, and governance guardrail catch - Agent-Jira-GitHub sequence diagram (Section 3.4): end-to-end interaction sequence covering the full agent contract
- Introduce MVP phase as the quickest, simplest demonstrable path to must-haves (bug fix workflow end-to-end), shifting Phase 0→1, Phase 1→2, Phase 2→3 - Add must/should/nice-to-have classification to all phases in Section 7 - Clarify MVP deferred items explicitly (FR-CROSS-13/14 to Phase 1; FR-FAIL-3/4 as nice-to-have) - Add Dependabot ADLC note (intentionally does not follow ADLC) - Add FR-TECH-3 underspecification check for parity with FR-FEAT-2 - Resolve OQ-8: non-empty AC field sufficient for MVP; structured format is Phase 1 - Fix FR-FAIL-3 contradiction: remove "silently" from dropped trigger - Fix ADLC diagram: governance failure arrows from LOAD, IMPL, and PCHECK - Fix sequence diagram: trigger routes through Jira, not direct to agent; halt notifications route through Jira/GitHub, not direct to Trigger; add Trigger monitoring note; governance events added to PR body update - Sharpen FR-CROSS-2 with per-system auth mechanism requirements (DefaultAzureCredential, GitHub token, Jira API key, model API key) — mechanisms must not be mixed - Sharpen FR-CROSS-3 with concrete externalized configuration requirement - Split FR-CROSS-4/8 between MVP (basic) and Phase 1 (full modular/configurable) - Add FR-CROSS-1 MVP/Phase 1 phasing note (basic logging in MVP; full in Phase 1) - Update FR-FAIL-1 with 30-minute default wall-clock suggestion - Collapse NFR-1 to pointer; make NFR-5 a summary with cross-references - Separate MVP and Phase 1 success metrics; move Dependabot, estimated effort, and guardrail metrics to Phase 1 (require telemetry or Phase 1 workflows) - Fix TBD link in JTBD-TRIAGE; update all Phase 0/1 references to MVP/Phase 1/2/3 - Add MVP definition to Glossary; update Contributor Phase column to "Phase 2" - Issue triage (JTBD-TRIAGE) leads Phase 2; feedback loop (JTBD-FEEDBACK) follows
…metrics - Restructure development phases: introduce MVP (bug fix only), renumber Phase 0→1, Phase 1→2, Phase 2→3; add must/should/nice-to-have lists - Sharpen FR-CROSS-2 with per-system auth requirements (GITHUB_TOKEN, Jira API token, DefaultAzureCredential, model API key); prohibit mixing - Add FR-CROSS-13 (prompt injection) and FR-CROSS-14 (protected paths) as Phase 1 requirements - Sequence diagram: route trigger through Jira, add halt notifications and Trigger monitoring note - ADLC diagram: add governance failure dotted arrows from LOAD/IMPL/PCHECK - Add FR-TECH-3 underspecification check - Split success metrics into MVP and Phase 1 tables - Add MVP definition to glossary - Resolve OQ-8: non-empty field sufficient for MVP - ToC sub-links for phases; FR-CROSS-4 Phase 1 distinction; FR-CROSS-5 as Phase 1 nice-to-have
roberthunterjr
force-pushed
the
ai-workflow-prd
branch
from
July 8, 2026 13:22
3d7b552 to
1cc97a7
Compare
Consistency fixes: - Standardize endpoint to "review-ready PR"; Draft PR is now only the intermediate step-5 steering artifact (Overview, Strategic Alignment, System Context, User Roles, JTBDs, glossary) - Promote basic FR-CROSS-4 (lint+tests) to MVP must-have; ADLC step 7 and FR-FAIL-2 depend on it - Add FR-GH-6 (Reviewer Notification); drop incorrect FR-CROSS-9 ref in ADLC step 8 - Rename "Time to Draft PR" -> "Time to review-ready PR" metrics - Raise FR-FAIL-1 default to 2 hours; reframe effort-vs-time metric as a relationship, not a target threshold - Scope FR-FAIL-6: MVP immediate halt, Phase 1 backoff retries - Consolidate Factory Operator into Operator (canonical) - Tighten FR-CROSS-3 -> FR-CROSS-8 to governance-config scope only - Add OQ-9 for epic-link exemption detection signal - Distinguish MoSCoW buckets from RFC 2119 keywords - Add MVP security risk-acceptance callout - Minor wording fix (FR-FAIL-4) New diagrams: - Logical component + trust-boundary diagram (Section 2) - Workflow-run state machine consolidating all terminal/recovery modes (Section 3.5) - Requirement dependency map for implementation ordering (Section 7) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3 tasks
2 tasks
Contributor
|
@roberthunterjr I'm going to close #66 but there are a few things that may be useful to you in that branch. Please take a look and cherry pick anything helpful. |
| - [Phase 2](#phase-2--community-pipeline-and-feedback-loop) | ||
| - [Phase 3](#phase-3--self-identification-of-tech-debt) | ||
| 8. [Success Metrics](#8-success-metrics) | ||
| 9. [Glossary](#9-glossary) |
Contributor
There was a problem hiding this comment.
FYI, both GitHub and VS Code can show the outline / table of contents automatically, so I generally avoid having a TOC that might get out of date.
|
|
||
| ### 1.3 Jobs to be Done (JTBD) | ||
|
|
||
| **JTBD-BUG**: When a bug ticket reaches "refined" status in Jira, I want to trigger a cloud agent |
Contributor
There was a problem hiding this comment.
Suggested change
| **JTBD-BUG**: When a bug ticket reaches "refined" status in Jira, I want to trigger a cloud agent | |
| **JTBD-BUG**: When a _bug ticket_ reaches "refined" status in Jira, I want to trigger a cloud agent |
| and advances it to a review-ready PR with all pre-checks passing, so that I can review a complete, | ||
| verified solution without consuming local development time or steering the agent interactively. | ||
|
|
||
| **JTBD-FEAT**: When a feature ticket with acceptance criteria reaches "refined" status in Jira, I |
Contributor
There was a problem hiding this comment.
Suggested change
| **JTBD-FEAT**: When a feature ticket with acceptance criteria reaches "refined" status in Jira, I | |
| **JTBD-FEAT**: When a _feature ticket_ with acceptance criteria reaches "refined" status in Jira, I |
Just helping the reader pick out the difference very quickly. If you like this suggestion, please apply it to the other JTBDs as well.
| **JTBD-DEP**: When a Dependabot PR is opened for a patch or minor version update, I want a cloud | ||
| agent to validate compatibility, run the pre-check suite, and auto-merge if all checks pass, so that | ||
| dependency hygiene is maintained without manual intervention. For major version updates, the agent | ||
| escalates for human review. |
Contributor
There was a problem hiding this comment.
The regular Dependabot workflow does everything except for the auto-merge. Is that a realistic possibility? I have never thought about auto merge before. I do like the idea here.
| agent to validate compatibility, run the pre-check suite, and auto-merge if all checks pass, so that | ||
| dependency hygiene is maintained without manual intervention. For major version updates, the agent | ||
| escalates for human review. | ||
|
|
Contributor
There was a problem hiding this comment.
Another Dependabot JTBD: when there is a build failure after a package update, we want GitHub Copilot to automatically try to fix the whatever broke.
| - <https://github.com/dotnet/runtime/tree/main/.github/agents> | ||
| - <https://github.com/anthropics/claude-code/blob/main/.github/workflows/claude-dedupe-issues.yml> | ||
| - <https://github.com/anthropics/claude-code/blob/main/.github/workflows/claude-issue-triage.yml> | ||
| - <https://github.com/anthropics/claude-code/blob/main/.github/workflows/lock-closed-issues.yml> |
Contributor
There was a problem hiding this comment.
Wherever a link has a real title to show, I suggest showing it, instead of having "bare links" in the markdown.
| SECRETS -.->|"injected at runtime"| AGENT | ||
| GOV -.->|"terminates loop"| AGENT | ||
| PRECHK -.->|"gates review-ready transition"| AGENT | ||
| ``` |
Contributor
There was a problem hiding this comment.
Is this flow a product requirement or an architectural design? I might be nitpicking too much. Just wondering if this content belongs in a design document rather than a requirements document.
| point estimate is set, and the ticket is linked to a parent epic (exempt if the ticket is | ||
| investigative or a one-off task; the signal the agent uses to detect an exempt ticket is an open | ||
| question — see OQ-9). If any criterion is not met, the agent must comment on the Jira | ||
| ticket with the specific reason for failure and halt without making code changes. |
Contributor
There was a problem hiding this comment.
I wonder if this is overly restrictive?
For example, requiring that the jira ticket have story points.
Might be the right call in this repo. Not necessary in the Docs repo.
Suggestion: make this a low priority. Human judgment to put in a label signaling "AI readiness" is all that is needed in the first few iterations on this work.
| **FR-CROSS-7 — Observability**: All workflows must emit telemetry (via OpenTelemetry or equivalent) | ||
| linking agent actions to their observed outcomes (pre-check results, test pass/fail, review | ||
| feedback). This telemetry must be structured to support future feedback loops into meta-harness | ||
| improvement. |
Contributor
There was a problem hiding this comment.
This is interesting, but honestly not something I expected to see.
Can you say more about the purpose of this requirement?
From a solution standpoint, is the session log telemetry for GitHub Copilot Cloud Agent sufficient for our needs? Note: this is now a solution question, rather than a requirements question.
| must be configurable without modifying workflow definitions — common mechanisms include a dedicated | ||
| governance configuration file in the meta-harness, GitHub Actions repository variables, or | ||
| environment settings scoped to the workflow. The specific mechanism is a design decision dependent | ||
| on harness selection (see OQ-2). |
Contributor
There was a problem hiding this comment.
For the July 31 goal, do you see loop engineering as a Must-have or Could-have priority?
| - **GitHub API**: authenticate via GitHub Actions `GITHUB_TOKEN` or a scoped personal access token | ||
| stored as a GitHub Actions secret. | ||
| - **Jira API**: authenticate via a Jira API token stored as a GitHub Actions secret. | ||
| - **Azure or other cloud-hosted resources** (e.g., Azure Functions, Cosmos DB, Storage): authenticate |
Contributor
There was a problem hiding this comment.
Is Azure still relevant at this point?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/PRD-agentic-workflow.md)docs/PRD-Fiona-skills.md), replacingdocs/fiona-skills-prd.mddocs/fiona-slack-prd.md→docs/PRD-Fiona-slack.mdwith formatting updatesCLAUDE.mdwith markdown authoring instructions for agentsmarkdownlint-cliand relaxes ordered-list style rule in.markdownlint.jsonTest plan
npx markdownlint-cli docs/*.md🤖 Generated with Claude Code