What happened
On PR #1124, the code agent (run) replaced the inline gh label create block in scripts/lib/labels.lib.sh with a call to forge_create_label(). This function exists in the code/review/fix/retro forge-ops files (github-code-ops.lib.sh, etc.), so it works when labels.lib.sh is bundled into post-code.sh. However, the triage ops files (github-triage-ops.lib.sh, gitlab-triage-ops.lib.sh, jira-triage-ops.lib.sh) define tracker_create_label() — not forge_create_label(). When labels.lib.sh is bundled into post-triage.sh or pre-triage.sh, the call to forge_create_label fails with exit code 127 under set -euo pipefail.
The CI script-test suite caught this immediately (44 test failures), and the review agent flagged it as critical. The fix agent resolved it in iteration 1 by adding forge_create_label() wrappers in all three triage ops files. The extra review+fix cycle cost ~$8.34 in agent spend and ~45 minutes of wall-clock time.
What could go better
The code-implementation skill already instructs the code agent to ask "Will this change affect other callers?" (step 8.7) and to search for all references when changing shared code (step 8.8). The agent failed to follow this guidance because it lacked repo-specific context about how scripts/lib/*.lib.sh files are consumed. Specifically:
- Lib files are bundled into multiple executable scripts via
make script-build, each with a different set of ops-file dependencies.
- Different agent types use different function-naming conventions: code/review/fix/retro ops use
forge_* prefix, triage ops use tracker_* prefix.
- A function called in a lib file must be available in every bundled context's dependency chain — not just the one the developer is most familiar with.
AGENTS.md currently documents commit format, simplicity principles, skill resolution, and harness env-var semantics, but says nothing about the bundled-script architecture. Without this context, the code agent treats labels.lib.sh as a standalone file rather than a shared component with multiple consumers.
Confidence: high that the missing documentation was the root cause. The code agent correctly rebuilt bundled scripts (make script-build) per the issue instructions, demonstrating awareness of the build step. But it had no guidance to verify that newly-introduced function calls resolve in all bundled contexts. The triage-ops naming convention (tracker_* vs forge_*) is a non-obvious architectural detail that generic skill guidance cannot anticipate.
Proposed change
Add a new section to AGENTS.md (e.g., section 9, "Bundled script architecture") documenting:
- How bundling works:
scripts/lib/*.lib.sh files are shared libraries sourced by scripts/*.src.sh files and compiled into standalone scripts/*.sh executables via make script-build.
- The ops-file naming split: code/review/fix/retro ops files use
forge_* prefix; triage ops files use tracker_* prefix. The triage ops files provide forge_* aliases where needed for cross-context compatibility.
- Cross-context verification rule: When modifying a lib file to introduce or change a function call, trace all
.src.sh files that source the lib (grep for the filename) and verify that the called function is defined in each bundled context's dependency chain. Run make script-test to confirm.
- The test command: After
make script-build, always run make script-test to verify bundled scripts pass the full test suite.
This gives the code agent the architectural context it needs to apply the generic "check all callers" guidance from the code-implementation skill to this repo's specific bundling pattern.
Validation criteria
On the next 3 code-agent PRs that modify files under scripts/lib/*.lib.sh, verify that: (1) the code agent traces bundled consumers before committing, (2) no CI script-test failures occur due to missing function definitions in bundled contexts, and (3) the review agent does not flag undefined-function findings caused by cross-context dependency gaps.
Generated by retro agent from #1124
What happened
On PR #1124, the code agent (run) replaced the inline
gh label createblock inscripts/lib/labels.lib.shwith a call toforge_create_label(). This function exists in the code/review/fix/retro forge-ops files (github-code-ops.lib.sh, etc.), so it works whenlabels.lib.shis bundled intopost-code.sh. However, the triage ops files (github-triage-ops.lib.sh,gitlab-triage-ops.lib.sh,jira-triage-ops.lib.sh) definetracker_create_label()— notforge_create_label(). Whenlabels.lib.shis bundled intopost-triage.shorpre-triage.sh, the call toforge_create_labelfails with exit code 127 underset -euo pipefail.The CI script-test suite caught this immediately (44 test failures), and the review agent flagged it as critical. The fix agent resolved it in iteration 1 by adding
forge_create_label()wrappers in all three triage ops files. The extra review+fix cycle cost ~$8.34 in agent spend and ~45 minutes of wall-clock time.What could go better
The code-implementation skill already instructs the code agent to ask "Will this change affect other callers?" (step 8.7) and to search for all references when changing shared code (step 8.8). The agent failed to follow this guidance because it lacked repo-specific context about how
scripts/lib/*.lib.shfiles are consumed. Specifically:make script-build, each with a different set of ops-file dependencies.forge_*prefix, triage ops usetracker_*prefix.AGENTS.md currently documents commit format, simplicity principles, skill resolution, and harness env-var semantics, but says nothing about the bundled-script architecture. Without this context, the code agent treats
labels.lib.shas a standalone file rather than a shared component with multiple consumers.Confidence: high that the missing documentation was the root cause. The code agent correctly rebuilt bundled scripts (
make script-build) per the issue instructions, demonstrating awareness of the build step. But it had no guidance to verify that newly-introduced function calls resolve in all bundled contexts. The triage-ops naming convention (tracker_*vsforge_*) is a non-obvious architectural detail that generic skill guidance cannot anticipate.Proposed change
Add a new section to
AGENTS.md(e.g., section 9, "Bundled script architecture") documenting:scripts/lib/*.lib.shfiles are shared libraries sourced byscripts/*.src.shfiles and compiled into standalonescripts/*.shexecutables viamake script-build.forge_*prefix; triage ops files usetracker_*prefix. The triage ops files provideforge_*aliases where needed for cross-context compatibility..src.shfiles that source the lib (grep for the filename) and verify that the called function is defined in each bundled context's dependency chain. Runmake script-testto confirm.make script-build, always runmake script-testto verify bundled scripts pass the full test suite.This gives the code agent the architectural context it needs to apply the generic "check all callers" guidance from the code-implementation skill to this repo's specific bundling pattern.
Validation criteria
On the next 3 code-agent PRs that modify files under
scripts/lib/*.lib.sh, verify that: (1) the code agent traces bundled consumers before committing, (2) no CI script-test failures occur due to missing function definitions in bundled contexts, and (3) the review agent does not flag undefined-function findings caused by cross-context dependency gaps.Generated by retro agent from #1124