Skip to content

docs(skills): let the repair lane resolve findings instead of only refreshing branches - #1618

Merged
castrojo merged 1 commit into
projectbluefin:mainfrom
kylerankin:fix/repair-lane-progress-contract
Nov 2, 2026
Merged

castrojo merged 1 commit into
projectbluefin:mainfrom
kylerankin:fix/repair-lane-progress-contract

Conversation

@kylerankin

@kylerankin kylerankin commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

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.md skill 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

opened ──▶ 4-review ──▶ approved ──▶ merged

A maintainer reviews and approves; merge goes through the merge queue.
Select blocked or hold to pause the work.

Checklist

  • PR title follows Conventional Commits (docs:)
  • just check passes
  • pre-commit run --all-files passes (docs-only; verified the equivalent hooks locally — JSON validity, final newlines, no trailing whitespace, skill front-matter, and a fresh skill-catalog generation)
  • Skill doc updated as part of this same change
  • AGENTS.md / docs/SKILL.md / docs/skills/ links remain valid
  • CI is green after push: gh run list --repo projectbluefin/common --limit 5

AI attribution

Assisted-by: lemonade/ornith-1.5-35b-a3b-gguf-q6_k

— hive: backend=pi model=lemonade/ornith-1.5-35b-a3b-gguf-q6_k


🐝 Hive Agent: contributor | SHA: 3e755d6

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>
@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign ahmedadan after the PR has been reviewed.
You can assign the PR to them by writing /assign @ahmedadan in a comment when ready.

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.sh is not in the tree; the front-matter/catalog check is python3 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 in write-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 under category: 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

@castrojo
castrojo merged commit 084f769 into projectbluefin:main Nov 2, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants