Repository navigation
docs(archdev-skill): store PR review annotations after every push, and verify before stopping - #27
Merged
Conversation
…d verify before stopping ArchDev shows a PR's AI summary, Start here list, and per-hunk risk labels only for a head with a github_pr_review_annotations row. Rows are keyed by the exact head SHA, so every push leaves the new head without one until the agent stores it. Sessions annotate most heads and skip the last push before stopping, which is the head reviewers open. The skill now owns this step (the firstlanding AGENTS.md directive is removed): SKILL.md beats 2 and 3 name it, monitor.md gains a 'PR review annotations' section with the moments, the four commands, and a stopping-point check with 'extract show pr.review-annotations <num> --json' or 'inspect metadata <num> --sha <head>'.
rafael-archastro
force-pushed
the
docs/archdev-skill-annotate-every-push
branch
from
September 23, 2026 20:58
783a740 to
24e8617
Compare
… widgets The skill named the AI summary, the Start here list, and the per-hunk labels as what a missing row costs. That inventory drifts with the UI (the Overview no longer shows a summary section as of today) and is not what an agent needs to know. Say the mechanism instead: ArchDev reads a PR's review annotations from the row for its exact head SHA, nothing carries over, and the PR opens unannotated until a row exists.
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
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.
Review on ArchCode
Problem and author intent
ArchDev reads a pull request's review annotations from the
github_pr_review_annotationsrow for its exact head SHA. Nothing carries over between heads, so every push leaves the PR unannotated until a row for the new head is stored.archdev publishwrites one;gh pr createandgit pushdo not.Observed today on ArchAstro/firstlanding#14946: the session stored rows for four heads within a minute of each push and skipped the last two, including the final push before it stopped. Reviewers opening the PR saw no annotations. The last push of a session is the one most often skipped and the head reviewers actually open.
The skill already said "store annotations before the
pr.*post" in one bullet under Report. That was easy to miss at the end of a session. The firstlanding repo also carried a copy of the instruction in AGENTS.md; that copy is being removed (ArchAstro/firstlanding#14983) so this skill is the single owner.What changed
archdev/SKILL.md: Monitor beat 2 says to store the head's annotations aftergh pr createand after every push that moves a PR head. Beat 3 adds a stopping-point check withextract show pr.review-annotations <num> --json, outside Factory sessions. The closing paragraph explains why (rows per head SHA, nothing carries over).archdev/references/monitor.md:extract showfrom the PR's checkout at its head;ExtractionNotFoundErrormeans no row for this head, any other error means the checkout is not at the PR head.donerow's "post when" column requires the PR's current head to have its annotations.inspect metadata <num> --sha "$(git rev-parse HEAD)".Testing
Docs only; no automated test covers skill prose. A review pass checked every command, flag, and error name against the CLI source (extract
show/run, the PR subject's HEAD-equals-PR-head rule, focus validation,inspect metadataordering) and its nine findings are folded in. Both verification commands were run against #14946 for a head with a row and a head without one; outputs match the text. This PR's own head was annotated by following the new section.Risk
Low. Instruction text only.