Repository navigation
docs(skills): let the repair lane resolve findings instead of only refreshing branches - #1618
Conversation
The repair lane had no written contract, so a branch a reviewer asked to change could be advanced by only rebasing or refreshing commits while its findings stayed open. This documents the observable progress contract every repair branch must satisfy: fix the reviewed findings, preserve main's inventory policy, regenerate only still-supported derived data, exercise the changed behavior, obtain a new exact-head review, and record a real repair -> review -> CI -> Hive merge receipt instead of a branch-update receipt. Refresh-only cycles now produce a diagnostic and an owning task. Hive-Run: projectbluefin#1613 Hive-Plan: repair-lane-progress-contract Hive-Spec: common#1613 Assisted-by: lemonade/ornith-1.5-35b-a3b-gguf-q6_k Signed-off-by: kylerankin <kylerankin@users.noreply.github.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: Needs approval from an approver in each of these files:Approvers can indicate their approval by writing |
There was a problem hiding this comment.
Summary: This change adds a written rule for the automated "repair lane" so a branch that a reviewer sent back must actually fix what was asked, not just re-sync itself. The document and its catalog entries are built correctly, but it says it fully closes the tracking issue even though that issue also demands two concrete pull requests in other repositories be repaired, which this text alone cannot do. One verification step also points at a check script that does not exist.
What I need from you: Change "Closes" to "Refs" for the issue and fix the script name (suggestions below).
intent-alignment
- PR closes #1613 but satisfies only part of its acceptance list (medium, PR body "Closes #1613"). Issue #1613 acceptance items 1–2 require that the source/doc changes on projectbluefin/utah#938 be made and verified, and that projectbluefin/utah-packages#804 be reconciled. A docs-only skill in this repository (
docs/skills/repair-lane.md,docs/SKILL.md:28,docs/skills/index.json,docs/skills/index.md:47) does neither; merging would auto-close the issue with those items unmet. Suggested PR-body edit:-Closes #1613. That issue reported ... +Refs #1613 (covers the "written progress contract" part; the #938 / #804 repairs remain open on that issue). That issue reported ...
- Item 5 reinterprets "current-head checks" (low,
docs/skills/repair-lane.md:65-69). The issue's acceptance item 2 pairs "current-head checks" with #804, whose blocking review says "CI has never run on this PR" — i.e. checks must run on the branch's current head. The skill instead turns it into a rule about pins pointing at an https release archive vs http, which appears nowhere in #1613. Suggested rewrite:5. **Checks run on the current head.** CI and local checks are run against the branch's current head commit, not an earlier one. A green check from a previous head, or a head with no CI run at all, is not evidence for the fix.
docs-currency
- Verification cites a script that does not exist (low,
docs/skills/repair-lane.md:137).scripts/check-skill-frontmatter.shis not in the tree; the front-matter/catalog check ispython3 scripts/generate_skill_index.py --check(.pre-commit-config.yaml:79,docs/skills/write-a-skill.md:98-102). Also, the repository's other policy skills (e.g.docs/skills/secrets-policy.md:120-124) do not include a self-maintenance item in Verification; it belongs inwrite-a-skill.md, not in this skill's own checklist. Suggested:(delete line 137)
style
- Advisory (low,
docs/skills/repair-lane.md:46-70): contract items 2–6 generalize symptoms specific to utah-packages#804 (inventory policy, source-lock sorting, removed count snapshots) into a cross-repository skill undercategory: meta. Most consumers of this catalog have no "source locks"; consider grouping these as "when the repository has derived inventory/lock files" so the generic items 1, 7–10 stand on their own. Not blocking.
No findings from: correctness, security.
Confidence: 3/5 (needs attention) — 1 medium finding; 2 perspectives requested changes
— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88
Summary: This writes down the rule for the "repair lane" — the automated process that fixes a pull request a reviewer said needs work — so it actually makes the requested fixes instead of only re-doing the same commits to look like progress. Without a written rule, a branch can keep rebasing or refreshing itself while the reviewer's concerns stay open, making it hard to tell whether a problem was really fixed. This makes that progress visible and honest, and stops a branch-update from being mistaken for a real fix.
What I need from you: Review it and approve it for the merge queue.
What does this change?
Adds a new
docs/skills/repair-lane.mdskill that defines the repair lane's observable progress contract, and registers it in the skill catalog (index.json/index.md) and the skill router (docs/SKILL.md).Why?
Refs #1613 (partial documentation only; actual review-finding repairs and the repair-to-review-to-CI-to-Hive-merge demonstration remain open). That issue reported the repair lane was advancing branches by only rebasing or refreshing commits while the reviewer's findings stayed open. The new skill requires each repair branch to fix the reviewed findings, preserve main's inventory policy, regenerate only still-supported derived data, exercise the changed behavior with the local checks, obtain a new exact-head review, and record a real repair -> review -> CI -> Hive merge receipt instead of a branch-update receipt. Refresh-only cycles must instead produce an actionable diagnostic and name an owning task.
PR pipeline
Checklist
docs:)just checkpassespre-commit run --all-filespasses (docs-only; verified the equivalent hooks locally — JSON validity, final newlines, no trailing whitespace, skill front-matter, and a fresh skill-catalog generation)AGENTS.md/docs/SKILL.md/docs/skills/links remain validgh run list --repo projectbluefin/common --limit 5AI attribution
— hive: backend=pi model=lemonade/ornith-1.5-35b-a3b-gguf-q6_k
🐝 Hive Agent:
contributor| SHA:3e755d6