refactor(docs): replace BACKLOG.md log with GitHub Issues scheme (#37)#38
Merged
Conversation
Move to issue-native work tracking so agents stop loading a 674-line log as live context. One home per thing: open work -> GitHub Issues (labels + templates, PR-wired review); decisions -> DESIGN.md; grounded RouterOS/QEMU facts -> the narrowest scoped instruction/doc/REPORT; shipped -> CHANGELOG; history -> git. - Labels: area:* (x10), P1-P4, research, needs-decision; applied to #23-#31/#36/#37. - New .github/ISSUE_TEMPLATE/{task,research,needs-decision} (each with Done-when). - CONTRIBUTING.md "Tracking work" is the canonical scheme; AGENTS/CLAUDE/general/ instruction-hygiene/DESIGN routers point to it (no more "log in BACKLOG"). - Extract durable knowledge kept only in BACKLOG into DESIGN.md (CLI principles, port-allocation rationale, Out of Scope, agent-discoverability) and a clean()/efi-vars code note; most facts were already canonical elsewhere. - BACKLOG.md 674 -> ~106 lines: scheme map + filed-issues index + unfiled checklist + decisions-owed + deferred. - Fix stale refs: docs/networking § P5, the lost Windows-TCG finding (suite passed; scp works without sshpass), and a CHANGELOG pointer to a missing entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
Warning Review limit reached
Next review available in: 33 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR migrates the project's work-tracking scheme from a single BACKLOG.md log to GitHub Issues. It adds new issue templates (task, research, needs-decision) and config, restructures BACKLOG.md into a work map, updates CONTRIBUTING.md with a tracking policy, and revises cross-references across DESIGN.md, instructions, MANUAL.md, docs, examples, and code comments. ChangesWork tracking migration
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Refactors the project’s work-tracking documentation away from a large, agent-loaded BACKLOG.md toward an issue-native scheme (Issues + labels + templates), while updating router docs/instructions to point at the new “one home per thing” policy and preserving a few durable facts in the appropriate long-lived docs.
Changes:
- Introduces GitHub Issue templates + a canonical “Tracking work” policy in
CONTRIBUTING.md. - Collapses
BACKLOG.mdinto a thin map/index plus a small unfiled checklist, and updates doc/instruction pointers accordingly. - Extracts/preserves key durable knowledge in the right places (e.g.,
DESIGN.mdadditions;clean()EFI vars rationale comment).
Reviewed changes
Copilot reviewed 25 out of 25 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
test/lab/mndp/REPORT.md |
Replaces a BACKLOG pointer with an inline verdict and revisit criteria. |
src/lib/quickchr.ts |
Adds an explanatory comment about why clean() must not delete efi-vars.fd on arm64. |
project-words.txt |
Adds unfiled to the cSpell project dictionary. |
MANUAL.md |
Updates “read next” guidance to reflect the new work-tracking scheme. |
examples/mndp/README.md |
Updates wording around the BACKLOG pointer to match “until filed” phrasing. |
examples/_template/README.md |
Updates the “friction found” template to link GitHub issues (not BACKLOG items). |
docs/qga-x86-macos-qemu10-investigation.md |
Replaces BACKLOG tracking reference with GitHub Issues label guidance. |
docs/networking.md |
Repoints design/work tracking references to DESIGN.md + area:networking Issues. |
DESIGN.md |
Adds rationale/constraints that previously lived only in BACKLOG; updates tracking language. |
CONTRIBUTING.md |
Adds the canonical “Tracking work” policy section and label taxonomy. |
CLAUDE.md |
Updates the “read these first” routing and end-of-session checklist to be issue-centric. |
BACKLOG.md |
Replaces the large backlog log with a short work-map/index and unfiled checklist. |
AGENTS.md |
Updates agent routing to describe issue-native tracking and discourage regrowing BACKLOG. |
.github/workflows/verify-extended.yml |
Updates comments to remove stale BACKLOG references and reflect known Windows/arm64 status. |
.github/ISSUE_TEMPLATE/task.md |
Adds a Task template with Done-when + grounding prompts. |
.github/ISSUE_TEMPLATE/research.md |
Adds a Research template focused on producing lab grounding (REPORT.md). |
.github/ISSUE_TEMPLATE/needs-decision.md |
Adds a Needs-decision template for contract-affecting changes. |
.github/ISSUE_TEMPLATE/config.yml |
Adds contact links pointing to the new scheme + design decisions. |
.github/instructions/testing.instructions.md |
Updates “done” guidance from BACKLOG-centric to issue/CHANGELOG-centric. |
.github/instructions/routeros-rest.instructions.md |
Updates the REST-timeout note language to fit the new tracking scheme. |
.github/instructions/instruction-hygiene.instructions.md |
Adds a rule: work items in Issues; durable facts in scoped docs. |
.github/instructions/general.instructions.md |
Updates end-of-session review checklist to be issue-centric. |
.github/instructions/examples.instructions.md |
Updates “friction found” + durable-fact guidance to reference issues/scoped docs. |
.github/instructions/ci.instructions.md |
Updates Windows integration notes based on observed results; repoints tracking. |
.agents/skills/quickchr-maintainer/SKILL.md |
Updates the skill’s checklist to reference Issues/CHANGELOG rather than BACKLOG. |
Comment on lines
+81
to
+84
| Do not copy the blocking-endpoint timers to normal REST calls. Treat 60s as a working | ||
| assumption inherited from centrs for ordinary REST requests, but do not add a quickchr clamp | ||
| until the REST-timeout reconciliation lab in `BACKLOG.md` confirms the rule and documents | ||
| any endpoint-specific exceptions. | ||
| until the REST-timeout reconciliation task (listed in `BACKLOG.md` until filed as an issue) | ||
| confirms the rule and documents any endpoint-specific exceptions. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/ISSUE_TEMPLATE/config.yml:
- Around line 1-5: The issue is that blank issue submission is currently allowed
in the issue template config, letting users skip the
Task/Research/Needs-decision templates and their required structure. Update the
configuration in config.yml so blank issues are disabled, unless you
intentionally want ad hoc support reports—in that case, document the exception
clearly alongside the existing contact_links entry.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 3b44c091-2ea3-4f86-a79a-3b779d868cb9
📒 Files selected for processing (25)
.agents/skills/quickchr-maintainer/SKILL.md.github/ISSUE_TEMPLATE/config.yml.github/ISSUE_TEMPLATE/needs-decision.md.github/ISSUE_TEMPLATE/research.md.github/ISSUE_TEMPLATE/task.md.github/instructions/ci.instructions.md.github/instructions/examples.instructions.md.github/instructions/general.instructions.md.github/instructions/instruction-hygiene.instructions.md.github/instructions/routeros-rest.instructions.md.github/instructions/testing.instructions.md.github/workflows/verify-extended.ymlAGENTS.mdBACKLOG.mdCLAUDE.mdCONTRIBUTING.mdDESIGN.mdMANUAL.mddocs/networking.mddocs/qga-x86-macos-qemu10-investigation.mdexamples/_template/README.mdexamples/mndp/README.mdproject-words.txtsrc/lib/quickchr.tstest/lab/mndp/REPORT.md
…n REST-timeout rule - .github/ISSUE_TEMPLATE/config.yml: blank_issues_enabled=false so every issue picks a template and lands with labels + a Done-when (CodeRabbit). - routeros-rest.instructions.md: state the "don't clamp normal REST timeouts" rule as a self-contained durable rule instead of pointing at an unfiled BACKLOG item (Copilot) — the work stays tracked in BACKLOG; the instruction doc now holds only the rule. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Author
|
Addressed both review comments in 2c2acfa:
|
mobileskyfi
added a commit
that referenced
this pull request
Jul 3, 2026
Second half of #37: with the Issue->PR scheme merged (#38), triage BACKLOG.md's "not yet filed" checklist into a curated set of GitHub Issues (the "one list" to comment on) -- grouped, not 1-to-1: - #39 anchors an optional centrs `exec` passthrough (needs-decision) and folds the centrs-owned cluster (exec soft-error, protocol-adapter, MAC-Telnet) as checklist items there, not as separate quickchr issues -- they're more involved than QEMU-focused quickchr and drove centrs' design. - #40 Windows, #41 platform-gaps, #42 cross-platform, #43 REST-grounding, #44 CLI/UX polish, #45 QEMU watch-items are triage umbrellas (research, done-when = break out sub-issues then close). - #46-#55 crisp singles; #56-#58 the port/config needs-decision calls. BACKLOG.md is now a rot-free map: browse-by-label query links for the live list, explicit numbers only for grounding anchors (#39/#40/#56-#58). Repoint the centrs MAC-Telnet note (examples/mndp) and the DESIGN port open-questions to the real issues. Left the self-contained REST-timeout rule in routeros-rest.instructions.md as-is (rules, not work pointers). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
What & why
BACKLOG.mdhad grown to 674 lines / 72 KB and was loaded as live agent context — the context-bloat / doc-rot risk #37 flags. It also mixed four kinds of content and dual-tracked with existing issues (#23/#24/#25 lived in both places).This moves to an issue-native scheme — one home per thing:
DESIGN.md.github/instructions/*.md, elsedocs/, elsetest/lab/<topic>/REPORT.mdCHANGELOG.mdChanges
area:*(×10),P1–P4,research,needs-decision; applied to CLI: addquickchr cpfor file transfer (upload/download) #23–examples/rollback: investigate ARM64 snapshot restore after loadvm #31, agent setup: follow-up cleanup decisions after Codex/Copilot review #36, Consider triaging BACKLOG.md open items into GitHub issues #37..github/ISSUE_TEMPLATE/{task,research,needs-decision}— each carries a Done-when;config.ymllinks the scheme.CONTRIBUTING.md"Tracking work" is the canonical description;AGENTS.md/CLAUDE.md/general/instruction-hygiene/DESIGNrouters point to it and stop telling agents to "log work in BACKLOG".DESIGN.md(CLI principles, port-allocation rationale, Out of Scope, agent-discoverability) and aclean()/efi-varscode comment. Most facts were already canonical elsewhere (bun-http/routeros-restinstructions,docs/networking.md, labREPORT.mds).docs/networking.md"§ P5" (section no longer existed), the lost Windows-TCG finding (full suite passed; scp works withoutsshpass), and a workflow comment pointing at a non-existent CHANGELOG entry.Scope note
Filing was reconcile-only by design (the maintainer's steer: don't triage future work now). Existing issues were re-labeled; no new issues were filed — genuinely-open items sit in the BACKLOG checklist for incremental filing.
Verification
bun run checkgreen (biome, tsc, markdownlint, cspell, validate-examples, shellcheck)Closes #37.
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores