From ec475073637af3b6fee832dd2848c5459b116e2e Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Thu, 27 Aug 2026 11:46:02 +0200 Subject: [PATCH 1/8] add agentic workflow for ai triage issue --- .gitattributes | 1 + .github/aw/actions-lock.json | 9 + .github/workflows/ai-issue-triage.md | 271 +++++++++++++++++++++++++++ 3 files changed, 281 insertions(+) create mode 100644 .gitattributes create mode 100644 .github/aw/actions-lock.json create mode 100644 .github/workflows/ai-issue-triage.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..1f7549b5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +.github/workflows/*.lock.yml linguist-generated=true \ No newline at end of file diff --git a/.github/aw/actions-lock.json b/.github/aw/actions-lock.json new file mode 100644 index 00000000..ba426924 --- /dev/null +++ b/.github/aw/actions-lock.json @@ -0,0 +1,9 @@ +{ + "entries": { + "github/gh-aw-actions/setup@v0.86.2": { + "repo": "github/gh-aw-actions/setup", + "version": "v0.86.2", + "sha": "6aab9e5b5c91c615506061f09bedd81a23babe3c" + } + } +} diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md new file mode 100644 index 00000000..e56f2cc1 --- /dev/null +++ b/.github/workflows/ai-issue-triage.md @@ -0,0 +1,271 @@ +--- +name: AI Issue Triage + +on: issue labeled ai-triage + +engine: + id: copilot + model: gpt-5-codex + +permissions: + contents: read + copilot-requests: write + +network: defaults + +runtimes: + python: + version: "3.12" + +tools: + bash: true + +pre-agent-steps: + - name: Verify Graphify graph + run: | + test -f .graphify/graph.json || { + echo "::error::.graphify/graph.json does not exist" + exit 1 + } + +mcp-servers: + graphify: + command: uvx + args: + - --from + - "graphifyy[mcp]==0.9.48" + - graphify-mcp + - .graphify/graph.json + allowed: + - query_graph + - get_node + - get_neighbors + - shortest_path + +safe-outputs: + add-comment: + target: triggering + max: 1 +--- + +# AI Issue Triage + +Analyze the triggering issue: + +${{ steps.sanitized.outputs.text }} + +Your goal is to produce a technical analysis that helps a software engineer: + +- understand the issue; +- understand the relevant parts of the codebase; +- identify the likely impact of the change; +- understand how to approach the implementation; +- identify the tests that should be added or updated; +- obtain a ready-to-use prompt for a coding LLM. + +## Investigation + +Start by understanding the issue and identifying the main concepts involved. + +Use Graphify as the primary navigation tool for the codebase. + +Use the Graphify MCP tools to: + +- find symbols related to the issue; +- inspect relevant nodes; +- inspect callers, callees and neighboring symbols; +- follow relationships between relevant components when useful. + +Do not treat the Graphify graph as the source of truth. + +After Graphify identifies relevant areas, inspect the actual repository source code before making conclusions. + +Use the repository filesystem to inspect the relevant files and verify how the implementation actually works. + +Also inspect relevant Markdown documentation because documentation files are not represented in the Graphify code graph. + +Look for useful documentation such as: + +- `README.md`; +- files under `docs/`; +- architecture or design documentation; +- configuration and deployment documentation; +- Markdown files located near the affected code. + +Do not read all documentation blindly. + +Use the issue and the code areas identified through Graphify to decide which documentation is relevant. + +If documentation and implementation disagree, treat the current source code as the source of truth and mention the discrepancy when relevant. + +Continue using Graphify iteratively when additional relationships or affected components need to be understood. + +Prefer the smallest relevant code surface needed to understand the issue. + +Do not propose unrelated refactors or architectural changes unless they are clearly required by the issue. + +Prefer simple changes that are consistent with the existing codebase and its current patterns. + +Do not modify repository files. + +Do not create branches, commits or pull requests. + +Do not invent files, symbols, APIs, behavior or implementation details that cannot be verified from the repository. + +If something cannot be determined confidently, explicitly mention it as an open question. + +## Output + +Post exactly one comment on the triggering issue using the following structure: + +### AI Technical Analysis + +#### Summary + +Briefly explain what the issue appears to require. + +Describe the expected result of the change without going into implementation details yet. + +#### Relevant Code + +List the main files, symbols, packages and components involved. + +For each relevant item: + +- include the concrete file path when known; +- include the relevant symbol when known; +- briefly explain why it is involved. + +Do not list files that are only loosely related to the issue. + +#### Relevant Documentation + +List documentation that provides useful requirements, architecture, configuration or implementation context. + +Briefly explain what useful information each document provides. + +Omit this section if no relevant documentation was found. + +#### Current Flow + +Explain how the relevant implementation currently works. + +Describe the execution or data flow when useful. + +Reference concrete files and symbols whenever possible. + +Focus only on the parts necessary to understand the issue. + +#### Likely Changes + +Describe the changes that would probably be required to implement the issue. + +Reference concrete files, symbols or components whenever possible. + +For each likely change, explain: + +- what would change; +- why it would change; +- how it relates to the issue. + +Do not include unrelated cleanup or refactoring. + +#### Impact + +Describe other components, callers, consumers, data flows or behaviors that could be affected by the change. + +Use Graphify relationships and the actual source code to identify the likely impact. + +Distinguish between: + +- directly affected code; +- possible secondary impact. + +Do not claim impact that cannot be supported by the repository. + +#### Tests + +Describe the tests that should be added or updated. + +Include: + +- the main expected behavior; +- regression coverage; +- relevant edge cases; +- integration or end-to-end tests when appropriate. + +Reference existing test files or test patterns when they are relevant. + +Prefer realistic tests over mocks when the existing repository makes that practical. + +#### Action Plan + +Provide a concrete and ordered implementation plan for solving the issue. + +The plan should be detailed enough that a software engineer could follow it step by step. + +For each step: + +1. reference the relevant file, package or symbol when known; +2. explain what should be inspected or changed; +3. explain why the step is necessary; +4. mention dependencies on previous steps when relevant. + +The plan should include: + +- implementation steps; +- schema or configuration changes if required; +- compatibility considerations if relevant; +- tests to add or update; +- validation commands or checks when they can be inferred from the repository. + +Keep the plan focused on the issue. + +Avoid overengineering, speculative abstractions and unrelated refactors. + +If multiple implementation approaches are possible, recommend the simplest approach that is consistent with the current codebase and briefly explain why. + +#### Suggested LLM Prompt + +Provide a ready-to-copy prompt that a software engineer can give to a coding LLM to implement the issue. + +The prompt must be based only on information verified during this analysis. + +Include: + +- a concise description of the issue; +- the relevant files, packages and symbols; +- the current behavior; +- the expected behavior; +- the proposed action plan; +- important implementation constraints; +- tests that should be added or updated; +- relevant edge cases; +- any known compatibility requirements. + +The prompt must explicitly instruct the coding LLM to: + +- inspect the actual repository before modifying code; +- verify that the analysis still matches the current source; +- follow existing repository patterns; +- keep the implementation simple; +- avoid overengineering; +- avoid unrelated refactors; +- avoid inventing APIs, files, symbols or behavior; +- add or update realistic tests; +- explain any necessary deviation from the proposed plan if the actual code requires it; +- run the relevant tests and validation commands when possible. + +Do not tell the coding LLM that the proposed implementation is guaranteed to be correct. + +The generated prompt should be directly copy-pasteable. + +Format it inside a fenced text block. + +#### Open Questions + +List anything that cannot be determined confidently from the issue, source code, Graphify graph or documentation. + +For each open question, briefly explain why it matters to the implementation. + +Omit this section if there are no meaningful open questions. From e4664176efa4548f1d93c8a670e1b7b0fdc0fab1 Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Thu, 27 Aug 2026 12:08:26 +0200 Subject: [PATCH 2/8] ignoring generate aw file --- .github/config/.licenserc.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/config/.licenserc.yaml b/.github/config/.licenserc.yaml index a492418d..84e0addc 100644 --- a/.github/config/.licenserc.yaml +++ b/.github/config/.licenserc.yaml @@ -8,6 +8,7 @@ header: paths-ignore: - ".github/config" + - ".github/aw" - "**/*.{md,MD}" - "LICENSE" - "NOTICE" From 716f874aaf1fd14a25680e51650b796acbf6efb2 Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Thu, 27 Aug 2026 12:17:45 +0200 Subject: [PATCH 3/8] update model --- .github/workflows/ai-issue-triage.md | 66 ++++++++++++++++++---------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md index e56f2cc1..21bb2fff 100644 --- a/.github/workflows/ai-issue-triage.md +++ b/.github/workflows/ai-issue-triage.md @@ -5,7 +5,8 @@ on: issue labeled ai-triage engine: id: copilot - model: gpt-5-codex + +model: gpt-5-codex permissions: contents: read @@ -78,11 +79,14 @@ Use the Graphify MCP tools to: Do not treat the Graphify graph as the source of truth. -After Graphify identifies relevant areas, inspect the actual repository source code before making conclusions. +After Graphify identifies relevant areas, inspect the actual repository source +code before making conclusions. -Use the repository filesystem to inspect the relevant files and verify how the implementation actually works. +Use the repository filesystem to inspect the relevant files and verify how the +implementation actually works. -Also inspect relevant Markdown documentation because documentation files are not represented in the Graphify code graph. +Also inspect relevant Markdown documentation because documentation files are not +represented in the Graphify code graph. Look for useful documentation such as: @@ -94,25 +98,32 @@ Look for useful documentation such as: Do not read all documentation blindly. -Use the issue and the code areas identified through Graphify to decide which documentation is relevant. +Use the issue and the code areas identified through Graphify to decide which +documentation is relevant. -If documentation and implementation disagree, treat the current source code as the source of truth and mention the discrepancy when relevant. +If documentation and implementation disagree, treat the current source code as +the source of truth and mention the discrepancy when relevant. -Continue using Graphify iteratively when additional relationships or affected components need to be understood. +Continue using Graphify iteratively when additional relationships or affected +components need to be understood. Prefer the smallest relevant code surface needed to understand the issue. -Do not propose unrelated refactors or architectural changes unless they are clearly required by the issue. +Do not propose unrelated refactors or architectural changes unless they are +clearly required by the issue. -Prefer simple changes that are consistent with the existing codebase and its current patterns. +Prefer simple changes that are consistent with the existing codebase and its +current patterns. Do not modify repository files. Do not create branches, commits or pull requests. -Do not invent files, symbols, APIs, behavior or implementation details that cannot be verified from the repository. +Do not invent files, symbols, APIs, behavior or implementation details that +cannot be verified from the repository. -If something cannot be determined confidently, explicitly mention it as an open question. +If something cannot be determined confidently, explicitly mention it as an open +question. ## Output @@ -124,7 +135,8 @@ Post exactly one comment on the triggering issue using the following structure: Briefly explain what the issue appears to require. -Describe the expected result of the change without going into implementation details yet. +Describe the expected result of the change without going into implementation +details yet. #### Relevant Code @@ -140,7 +152,8 @@ Do not list files that are only loosely related to the issue. #### Relevant Documentation -List documentation that provides useful requirements, architecture, configuration or implementation context. +List documentation that provides useful requirements, architecture, +configuration or implementation context. Briefly explain what useful information each document provides. @@ -172,9 +185,11 @@ Do not include unrelated cleanup or refactoring. #### Impact -Describe other components, callers, consumers, data flows or behaviors that could be affected by the change. +Describe other components, callers, consumers, data flows or behaviors that +could be affected by the change. -Use Graphify relationships and the actual source code to identify the likely impact. +Use Graphify relationships and the actual source code to identify the likely +impact. Distinguish between: @@ -196,13 +211,15 @@ Include: Reference existing test files or test patterns when they are relevant. -Prefer realistic tests over mocks when the existing repository makes that practical. +Prefer realistic tests over mocks when the existing repository makes that +practical. #### Action Plan Provide a concrete and ordered implementation plan for solving the issue. -The plan should be detailed enough that a software engineer could follow it step by step. +The plan should be detailed enough that a software engineer could follow it step +by step. For each step: @@ -223,11 +240,13 @@ Keep the plan focused on the issue. Avoid overengineering, speculative abstractions and unrelated refactors. -If multiple implementation approaches are possible, recommend the simplest approach that is consistent with the current codebase and briefly explain why. +If multiple implementation approaches are possible, recommend the simplest +approach that is consistent with the current codebase and briefly explain why. #### Suggested LLM Prompt -Provide a ready-to-copy prompt that a software engineer can give to a coding LLM to implement the issue. +Provide a ready-to-copy prompt that a software engineer can give to a coding LLM +to implement the issue. The prompt must be based only on information verified during this analysis. @@ -253,10 +272,12 @@ The prompt must explicitly instruct the coding LLM to: - avoid unrelated refactors; - avoid inventing APIs, files, symbols or behavior; - add or update realistic tests; -- explain any necessary deviation from the proposed plan if the actual code requires it; +- explain any necessary deviation from the proposed plan if the actual code + requires it; - run the relevant tests and validation commands when possible. -Do not tell the coding LLM that the proposed implementation is guaranteed to be correct. +Do not tell the coding LLM that the proposed implementation is guaranteed to be +correct. The generated prompt should be directly copy-pasteable. @@ -264,7 +285,8 @@ Format it inside a fenced text block. #### Open Questions -List anything that cannot be determined confidently from the issue, source code, Graphify graph or documentation. +List anything that cannot be determined confidently from the issue, source code, +Graphify graph or documentation. For each open question, briefly explain why it matters to the implementation. From 1d82db62711ab61ce6eef21da96a564c5806f78a Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Fri, 28 Aug 2026 09:51:53 +0200 Subject: [PATCH 4/8] fix: configure ai triage MCP runtime --- .github/workflows/ai-issue-triage.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md index 21bb2fff..b5f2dcb3 100644 --- a/.github/workflows/ai-issue-triage.md +++ b/.github/workflows/ai-issue-triage.md @@ -10,6 +10,7 @@ model: gpt-5-codex permissions: contents: read + issues: read copilot-requests: write network: defaults @@ -31,12 +32,15 @@ pre-agent-steps: mcp-servers: graphify: - command: uvx - args: + container: "ghcr.io/astral-sh/uv:0.12.7-python3.12-alpine" + entrypoint: "uvx" + entrypointArgs: - --from - "graphifyy[mcp]==0.9.48" - graphify-mcp - - .graphify/graph.json + - \${GITHUB_WORKSPACE}/.graphify/graph.json + mounts: + - \${GITHUB_WORKSPACE}:\${GITHUB_WORKSPACE}:ro allowed: - query_graph - get_node From 8cc95b6eaa25b6e07f64cc8abcbee9a71d982b76 Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Fri, 28 Aug 2026 10:22:48 +0200 Subject: [PATCH 5/8] fix: mount graphify workspace correctly --- .github/workflows/ai-issue-triage.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md index b5f2dcb3..344ad711 100644 --- a/.github/workflows/ai-issue-triage.md +++ b/.github/workflows/ai-issue-triage.md @@ -38,9 +38,10 @@ mcp-servers: - --from - "graphifyy[mcp]==0.9.48" - graphify-mcp - - \${GITHUB_WORKSPACE}/.graphify/graph.json + - --graph + - /workspace/.graphify/graph.json mounts: - - \${GITHUB_WORKSPACE}:\${GITHUB_WORKSPACE}:ro + - \${GITHUB_WORKSPACE}:/workspace:ro allowed: - query_graph - get_node From d1ea0936c83f681dffed7f4c7a6972e737901312 Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Fri, 28 Aug 2026 10:50:07 +0200 Subject: [PATCH 6/8] fix: use configured graphify graph --- .github/workflows/ai-issue-triage.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md index 344ad711..da279ac8 100644 --- a/.github/workflows/ai-issue-triage.md +++ b/.github/workflows/ai-issue-triage.md @@ -82,6 +82,15 @@ Use the Graphify MCP tools to: - inspect callers, callees and neighboring symbols; - follow relationships between relevant components when useful. +IMPORTANT: The Graphify MCP server is already configured with the correct +repository graph at startup. When calling any Graphify MCP tool, do not pass +`project_path`; omit it entirely from every Graphify call. Do not pass +`${{ github.workspace }}`, `${GITHUB_WORKSPACE}`, `/workspace`, `.graphify`, or +any repository path as `project_path`. Let the Graphify MCP server use its +configured default graph, which is the authoritative navigation graph for this +workflow. This applies to `query_graph`, `get_node`, `get_neighbors`, and +`shortest_path`. + Do not treat the Graphify graph as the source of truth. After Graphify identifies relevant areas, inspect the actual repository source From 81d29c4e13d415591050382bb7005a061c3e433a Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Fri, 28 Aug 2026 11:31:09 +0200 Subject: [PATCH 7/8] fix: require ai triage comment output --- .github/workflows/ai-issue-triage.md | 73 ++++++++++++---------------- 1 file changed, 30 insertions(+), 43 deletions(-) diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md index da279ac8..6f290a00 100644 --- a/.github/workflows/ai-issue-triage.md +++ b/.github/workflows/ai-issue-triage.md @@ -141,7 +141,19 @@ question. ## Output -Post exactly one comment on the triggering issue using the following structure: +After completing a successful triage analysis, you MUST call the `add-comment` +safe-output tool exactly once. Pass the complete `### AI Technical Analysis` +as the body of that `add-comment` call. + +Do not merely return the analysis in the final agent response. Do not assume +normal agent output will automatically become a GitHub comment. Do not call +`noop` after a successful analysis. A successful triage MUST end with exactly +one `add-comment` safe-output request. Use `noop` only when there is genuinely +no actionable analysis to provide. If required information is missing and +prevents a reliable analysis, use the appropriate missing-data behavior. Do +not emit both `add-comment` and `noop` for a successful triage. + +The comment must use the following structure: ### AI Technical Analysis @@ -183,19 +195,22 @@ Reference concrete files and symbols whenever possible. Focus only on the parts necessary to understand the issue. -#### Likely Changes - -Describe the changes that would probably be required to implement the issue. - -Reference concrete files, symbols or components whenever possible. +#### Implementation Plan -For each likely change, explain: +Provide one concrete, ordered plan for solving the issue. Combine the changes, +locations, reasons, dependencies, compatibility considerations, relevant +implementation patterns, tests and validation in this section. Name concrete +files, packages and symbols whenever known. Prefer exact existing symbols over +generic wording and reuse verified patterns from the repository where possible. -- what would change; -- why it would change; -- how it relates to the issue. +Clearly distinguish facts directly confirmed from source, Graphify, +configuration or documentation from the smallest proposed implementation +change. Mark unresolved requirements or decisions as open questions. Do not +present proposals or uncertainties as verified behavior. -Do not include unrelated cleanup or refactoring. +Avoid speculative architecture, invented configuration contracts, new +abstractions that the code does not clearly require, unrelated refactors and +unverified files, symbols or APIs. #### Impact @@ -228,41 +243,13 @@ Reference existing test files or test patterns when they are relevant. Prefer realistic tests over mocks when the existing repository makes that practical. -#### Action Plan - -Provide a concrete and ordered implementation plan for solving the issue. - -The plan should be detailed enough that a software engineer could follow it step -by step. - -For each step: - -1. reference the relevant file, package or symbol when known; -2. explain what should be inspected or changed; -3. explain why the step is necessary; -4. mention dependencies on previous steps when relevant. - -The plan should include: - -- implementation steps; -- schema or configuration changes if required; -- compatibility considerations if relevant; -- tests to add or update; -- validation commands or checks when they can be inferred from the repository. - -Keep the plan focused on the issue. - -Avoid overengineering, speculative abstractions and unrelated refactors. - -If multiple implementation approaches are possible, recommend the simplest -approach that is consistent with the current codebase and briefly explain why. - #### Suggested LLM Prompt Provide a ready-to-copy prompt that a software engineer can give to a coding LLM to implement the issue. -The prompt must be based only on information verified during this analysis. +The prompt must be based only on information verified during this analysis and +the proposed steps in the Implementation Plan. Include: @@ -270,7 +257,7 @@ Include: - the relevant files, packages and symbols; - the current behavior; - the expected behavior; -- the proposed action plan; +- the proposed Implementation Plan; - important implementation constraints; - tests that should be added or updated; - relevant edge cases; @@ -291,7 +278,7 @@ The prompt must explicitly instruct the coding LLM to: - run the relevant tests and validation commands when possible. Do not tell the coding LLM that the proposed implementation is guaranteed to be -correct. +correct. Keep verified facts, proposed changes and open questions distinct. The generated prompt should be directly copy-pasteable. From 99a98e6202b6f455543df9c14724a332e098510e Mon Sep 17 00:00:00 2001 From: Antonio Ceppellini Date: Fri, 28 Aug 2026 14:12:04 +0200 Subject: [PATCH 8/8] improve ai triage system boundary analysis --- .github/workflows/ai-issue-triage.md | 122 ++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ai-issue-triage.md b/.github/workflows/ai-issue-triage.md index 6f290a00..8da91391 100644 --- a/.github/workflows/ai-issue-triage.md +++ b/.github/workflows/ai-issue-triage.md @@ -115,12 +115,104 @@ Do not read all documentation blindly. Use the issue and the code areas identified through Graphify to decide which documentation is relevant. +When transport, configuration or runtime infrastructure changes, inspect the +concrete operational surfaces identified by the affected code. Look for +relevant `.env` files, Docker or compose files, broker initialization scripts, +Kubernetes or Helm manifests, CI fixtures, test infrastructure, configuration +examples, README tables and architecture documentation. Use discovered +identifiers such as environment variables, queue or stream names, config fields +and service names to find their consumers. Do not scan the whole repository +blindly. + If documentation and implementation disagree, treat the current source code as the source of truth and mention the discrepancy when relevant. Continue using Graphify iteratively when additional relationships or affected components need to be understood. +### System Boundaries and Contracts + +Recognize when the issue crosses a system boundary, such as a producer and +consumer, queue or stream, message broker, API, RPC, serialization format, +event-driven interface, persistence boundary, external service contract or +protocol/data-format migration. + +When a boundary is involved, investigate the contract and logical semantics, +not only the local implementation. Do not assume that changing a transport or +library preserves the existing behavior. + +When relevant and supported by evidence, determine: + +- the logical unit of work or data; +- whether one logical operation uses one or multiple physical messages, + requests or records; +- framing, metadata and discriminators; +- correlation identifiers and ordering requirements; +- completion or boundary markers; +- deduplication and idempotency expectations; +- acknowledgement, commit, offset or checkpoint semantics; +- retry, replay and partial-processing behavior; +- malformed-input and failure behavior; +- compatibility and versioning requirements. + +Use only the dimensions that matter to the issue. Do not produce a protocol +checklist mechanically when the issue does not provide evidence of stateful or +cross-boundary behavior. + +When analyzing a consumer change, look for the corresponding producer or +upstream contract when it is available. When analyzing a producer change, look +for downstream consumers. Use Graphify relationships, source code, tests, +shared schemas or models, configuration, documentation and local Docker or +test infrastructure to trace that contract. + +If the relevant producer or consumer is in another repository that is not +available, do not invent its behavior. State the required external contract as +an Open Question and name the upstream or downstream component that must be +checked. + +When reusing an existing implementation pattern, distinguish explicitly +between: + +1. structural behavior verified as reusable, such as construction, lifecycle, + callbacks or reconnect handling; +2. behavior that is only analogous; +3. protocol and business semantics that still require independent verification. + +Reuse verified structural patterns, but independently verify protocol and +business semantics. Shared transports, libraries or APIs do not by themselves +establish equivalent message granularity, offset strategy, commit behavior or +replay semantics. + +### Progress and Failure Semantics + +For stateful or replayable code involving ACKs, offsets, checkpoints, +transactions, commits, cursors or persistent progress markers, determine the +logical success boundary: + +- what must complete before progress is acknowledged; +- whether progress applies to one physical input or a larger logical + operation; +- what is replayed after a restart; +- whether early commits can lose data; +- whether late commits can duplicate side effects; +- whether processing is idempotent. + +Do not copy acknowledgement or offset behavior from another consumer without +verifying that its logical unit and failure semantics are the same. + +When malformed input or processing errors are relevant, determine the actual +behavior: log and skip, retry, acknowledge or reject, dead-letter, stop, +continue, restart, replay, or clean up partial state. Label this behavior as +verified or proposed. If the repository and issue do not establish the required +policy, put the decision in Open Questions instead of inventing one. + +If multiple inputs may contribute to one logical result, determine how they are +correlated, where incomplete state is stored, how completion is detected, what +happens to old or incomplete state, whether all expected components are +required, when side effects occur, when progress is committed, and what +happens on restart. Apply this only when repository evidence suggests such +state. + Prefer the smallest relevant code surface needed to understand the issue. Do not propose unrelated refactors or architectural changes unless they are @@ -203,6 +295,12 @@ implementation patterns, tests and validation in this section. Name concrete files, packages and symbols whenever known. Prefer exact existing symbols over generic wording and reuse verified patterns from the repository where possible. +For each relevant step, include the verified current behavior, the smallest +proposed change, the structural pattern to reuse, and any semantic behavior +that must not be inferred from that pattern. Include ordering or dependency, +compatibility, failure/progress semantics and validation when they affect the +step. Keep steps concise when those dimensions are not relevant. + Clearly distinguish facts directly confirmed from source, Graphify, configuration or documentation from the smallest proposed implementation change. Mark unresolved requirements or decisions as open questions. Do not @@ -238,6 +336,15 @@ Include: - relevant edge cases; - integration or end-to-end tests when appropriate. +Derive tests from the new state transition or failure mode introduced by the +issue, rather than listing generic categories. When supported by the +implementation semantics, consider logical completion boundaries, partial +operations, restart/replay, progress initialization and resume, malformed +input before progress, malformed input after partial state, +ordering/correlation, duplicate input, missing components, shutdown/reconnect +and unchanged downstream behavior. Recommend only the cases relevant to the +issue and avoid inflating the test list. + Reference existing test files or test patterns when they are relevant. Prefer realistic tests over mocks when the existing repository makes that @@ -263,6 +370,15 @@ Include: - relevant edge cases; - any known compatibility requirements. +When a system boundary is relevant, carry verified facts about framing, +correlation, logical completion, progress/acknowledgement and replay or failure +behavior into this prompt. If those facts are unresolved, instruct the coding +LLM to verify the producer/consumer contract before implementing. Preserve the +distinction between a structural pattern that can be reused and protocol +semantics that must not be copied without verification. For example, it may be +appropriate to reuse consumer construction while independently verifying its +offset behavior. + The prompt must explicitly instruct the coding LLM to: - inspect the actual repository before modifying code; @@ -289,6 +405,10 @@ Format it inside a fenced text block. List anything that cannot be determined confidently from the issue, source code, Graphify graph or documentation. -For each open question, briefly explain why it matters to the implementation. +An Open Question must materially affect correctness or compatibility, cannot be +answered from the inspected evidence, and require product, protocol, upstream +or operational clarification. For each one, state the unknown decision, why it +matters, and which component or source should be checked to resolve it. Do not +include low-value speculative questions. Omit this section if there are no meaningful open questions.