Repository navigation
docs: add the swe-router rubric design notes - #41
Merged
Merged
Conversation
vend/swe-router/rubric.md states the six questions the router asks; nothing in this repository said why those six. This adds the reasoning, ported from upstream's phase-0 design notes. Not a verbatim port. Upstream wrote the page BEFORE the rubric shipped, so three passages describe as pending what PR #33 has since delivered, and each was verified against the shipped files before being rewritten: - The header said the shipped skill "still uses the older design, a consequence floor and a complexity tier" and pointed at the fork tag swe-router-floor-tier, which is not in this repository's history. The shipped skill is the rubric. Reframed as what it now is -- the reasoning behind rubric.md -- with the floor-and-tier version named as the thing it replaced and why. - Step 4 said route.py "knows four tier names rather than bucket names" and that when_unsure awaited phase 1. Both are live: route.py defines BUCKETS = ("easy", "moderate", "hard", "very_hard"), and --confidence low returns status "unsure" with no recommendation. - "Which file holds what" described an in-flight move of rubric.md and routing-policy.json between directories. They are vended now. Model names abstracted to class, per the convention the other analysis pages use, and the page says so where the figures appear. The closing "What remains before it ships" section listed work PR #33 completed, so it is replaced with "What shipped" plus the two caveats that did NOT change by shipping: one repository, one run per model per task, and a saving measured against always using the costliest model. Every number in the page was checked against the shipped vend/swe-router/routing-policy.json before republishing: bars 60/70/75, +5 when verification is 2, buckets 0-1 / 2-3 / 4-5 / 6-8, tie band 3 points, and "bucketing": "absolute" -- which is also the page's own finding, that relative bucketing and a per-model fitted line did no better. Linked from two places a reader would look: a documentation-map row in the root README beside the SKILL.md row, and the sentence in vend/swe-router/README.md that introduces the six questions without justifying them. Repo-wide link sweep over 77 markdown files reports only the pre-existing SUPPORT.md -> ../../issues GitHub idiom. 635 tests pass, no new failures.
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.
Why
vend/swe-router/rubric.mdstates the six questions the router asks. Nothing in this repository said why those six. A reader who installs the skill can see the mechanism and has no way to evaluate the design.This is the first of the rubric docs upstream has that we don't — 3 of 39 rubric-related paths came over in PR #33 (the rubric itself,
swe_router_rubric.pyand its tests); the 36 underdocs/anddocs/metrics/did not.Not a verbatim port
Upstream wrote this page before the rubric shipped, so three passages describe as pending what PR #33 has since delivered. Each was verified against the shipped files before rewriting:
mainswe-router-floor-tierroute.py"knows four tier names rather than bucket names"BUCKETS = ("easy", "moderate", "hard", "very_hard")when_unsure"phase 1 implements that in the skill"--confidence lowreturns statusunsurewith no recommendationPorting it as-is would have published a plan for a future that already happened.
The closing "What remains before it ships" section listed work PR #33 completed, so it's replaced by "What shipped" — plus the two caveats that didn't change by shipping: one repository, one run per model per task, and a saving measured against always using the costliest model.
Every number re-checked against the shipped policy
Before republishing figures I diffed them against
vend/swe-router/routing-policy.json:"bucketing": "absolute"That last one is also the page's own finding — relative bucketing and a per-model fitted line both failed to beat absolute buckets, because 21 tasks run once each can't separate them. Nice to be able to confirm the shipped config matches the conclusion.
Policy
Model names abstracted to class, per the convention the other analysis pages use, and the page states that where the figures appear. Zero real model names remain (checked). The three retained findings are the ones that bound how far to trust the router:
Discoverability
Linked from the two places a reader would look: a documentation-map row in the root README beside the
SKILL.mdrow, and the sentence invend/swe-router/README.mdthat introduces the six questions without justifying them.Checks
Repo-wide link sweep over 77 markdown files, resolving anchors as well as paths, reports only the pre-existing
SUPPORT.md → ../../issuesGitHub idiom. 635 tests pass, no new failures.Still unported, for reference
-evaluation.md(162L, 12 model mentions) and-scores.md(138L, 5) are results pages needing a full abstraction pass; the 4 per-dataset score pages include two for thecli-cli-v1dataset, which isn't here either; and the 25 replay JSONs underdocs/metrics/swe-router-rubric-replays/would re-introduce that directory wholesale.