Background
In githubnext/apm, later Crane PR comments needed a reliable way to explain what a newly accepted commit actually did. Sometimes score fields, issue comments, or state-file summaries are unavailable, stale, or too sparse. The commit itself should carry enough structured information to be a fallback source.
APM updated its local Crane workflow prompt so accepted iteration commits include a compact Changes: section before the Run: URL.
Problem
Today an accepted Crane commit may only have a subject and a run URL. That is not enough for downstream summaries, PR comments, or issue updates to reconstruct the useful reviewer-facing facts.
When a PR has many iteration commits, reviewers need to know which module, milestone, or command family each commit advanced. A generic subject plus a workflow link forces everyone to open logs.
Proposed implementation
Update workflows/crane.md so Step 5a requires accepted iteration commit messages to use this shape:
[Crane: {migration-name}] Iteration <N>: <short description>
Changes:
- <compact bullet describing the main migrated unit or behavior change>
- <optional second bullet with test, parity, or milestone movement>
Run: {run_url}
Guidance:
- Keep
Changes: compact and structured.
- Prefer one or two bullets, three max.
- Mention the migrated unit or behavior, not generic process.
- Mention test or parity movement when useful.
- Keep
Run: as the final evidence link.
The accepted-iteration summary logic should then be allowed to fall back to the commit subject plus Changes: bullets when richer state is missing.
Suggested test coverage
Add a prompt test asserting:
- The commit subject template is present.
Changes: appears before Run: {run_url}.
- The prompt says the
Changes: block is used as summary fallback.
Acceptance criteria
- Accepted Crane commits contain structured
Changes: bullets.
- Later PR or issue comments can summarize a commit without reading workflow logs.
- Existing commit subject and run-link behavior is preserved.
- The prompt test prevents regressions.
Provenance
This came from the githubnext/apm migration, where maintainer-facing summaries needed to describe what happened in each new Crane commit, not just that a commit was pushed.
Background
In githubnext/apm, later Crane PR comments needed a reliable way to explain what a newly accepted commit actually did. Sometimes score fields, issue comments, or state-file summaries are unavailable, stale, or too sparse. The commit itself should carry enough structured information to be a fallback source.
APM updated its local Crane workflow prompt so accepted iteration commits include a compact
Changes:section before theRun:URL.Problem
Today an accepted Crane commit may only have a subject and a run URL. That is not enough for downstream summaries, PR comments, or issue updates to reconstruct the useful reviewer-facing facts.
When a PR has many iteration commits, reviewers need to know which module, milestone, or command family each commit advanced. A generic subject plus a workflow link forces everyone to open logs.
Proposed implementation
Update
workflows/crane.mdso Step 5a requires accepted iteration commit messages to use this shape:Guidance:
Changes:compact and structured.Run:as the final evidence link.The accepted-iteration summary logic should then be allowed to fall back to the commit subject plus
Changes:bullets when richer state is missing.Suggested test coverage
Add a prompt test asserting:
Changes:appears beforeRun: {run_url}.Changes:block is used as summary fallback.Acceptance criteria
Changes:bullets.Provenance
This came from the githubnext/apm migration, where maintainer-facing summaries needed to describe what happened in each new Crane commit, not just that a commit was pushed.