Skip to content

docs(backlog): triage all 272 open issues into docs/backlog/ - #1996

Open
jcschaff wants to merge 6 commits into
masterfrom
worktree-bug+backlog
Open

docs(backlog): triage all 272 open issues into docs/backlog/#1996
jcschaff wants to merge 6 commits into
masterfrom
worktree-bug+backlog

Conversation

@jcschaff

@jcschaff jcschaff commented Aug 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

A grooming pass over all 272 open issues in this repo, cross-referenced against
project board #1, written up as 16 documents
under docs/backlog/.

This PR changes no issues, labels, or board fields. Everything in it is a proposal for a human
to accept, reject, or amend. Snapshot date: 2026-08-19.

What's in it

Doc What it is
README.md Index + the shape of the backlog (age, board coverage, description quality, ownership)
00-method.md The triage plan — 5 dispositions, 7 decision rules, who decides what, 6-step sequencing
01-close-and-verify.md 14 close candidates, with evidence
02-needs-refinement.md 50 unworkable issues, grouped by what is missing rather than by topic
03-board-hygiene.md Metadata problems that block the rest of grooming
04-epic-map.md 24 epics, 4 overlapping pairs, and 5 strategic decisions
10–19 Ten thematic groups

Every open issue appears in exactly one group table. Verified programmatically: 271 rows across
the group docs plus #1032 in the epic map, no duplicates, no omissions.

Findings worth acting on

The board's scoring model is Priority = Importance + Simplicity — exact on 56 of 57 ranked
issues, mean absolute error 0.09, with no competing formula above 15/57. Jim identified the shape
of this; the data confirms it. It resolves the ranking direction (higher Priority = do sooner)
and shows Priority is a derived total rather than an independent judgment. Three things follow:
#1495's arithmetic has drifted (stored 5, computes to 10); four issues have Importance scored
but Priority never computed, so they never enter the queue — #1473 and #1451 both compute
to 12, tying the highest score on the board, and have been in Pool since 2025; and because
ease is added rather than multiplied, a Byzantine (1) item caps at Priority 11 however
important it is, which is why the accessibility programme ranks low and why it probably belongs
outside the queue rather than competing on a score it cannot win.

55 open issues are not on the board at all — and they skew recent and well-described: the
entire 2026 SpringSaLaD grooming set, the field-viewer train, all six August infrastructure
issues, three epics. The board is stale at the new end, not the old end. Bulk-adding them is
roughly 30 minutes and is the cheapest high-value step in the plan.

45 issues carry labels naming shipped releases (VCell-7.6.0 on 26 alone, Next Release on
19). The current line is 8.0.27.01.

107 of 272 issues (39%) have a body under 200 characters. 73 issues are a July-2022 bulk
import of a spreadsheet, ~34 of them with empty bodies — #201's body is the tell:
"Original Todo list has ?? by this item." These need one session with their authors, not a year
of individual refinement.

Four issues are marked Done on the board but are still open. 14 close candidates in total;
six are verified against the working tree or git log (e.g. #1647 has commit
e79926b50a Fixed incorrect acot math!!!; #1686's PR #1685 is merged).

Four pairs of epics overlap (#1038/#1751, #1199/#1008, the three SpringSaLaD
containers, and three Quarkus/API epics), and five strategic decisions each gate a
double-digit number of issues — Postgres migration, desktop-vs-browser PDE viewer, standing of the
2022 cohort, whether accessibility is a dated mandate, and how far to pursue BioSimulators
conformance.

Two items I'd flag as under-ranked on severity: #490 (name collisions can make the solver
"run and produce incorrect results" — silent wrong science, currently mid-rank) and #1874
(SpringSaLaD's diffusion-limit check is off by ~600× and is off-board).

Caveats

  • #748 could not be resolved — the board says Done, I found no such script, and it may have
    been obsoleted by the Kubernetes migration. Flagged as an open question, not asserted.
  • #1646 is relayed from the board's Done status; I could not isolate a commit confirming it.
  • The ten thematic groups are a reading aid, not a proposed label scheme. Several issues
    genuinely belong to two groups; each was assigned one so counts sum cleanly. Converting these
    into GitHub labels deserves its own conversation — the repo already has 32.

Reviewing this

The useful review is on the judgments, not the prose: whether the close candidates are really
closeable, whether the epic merges are right, and whether the five decisions are the right five.
Corrections are cheap — this is documentation, and it is explicitly a snapshot.

The scoring-model question that the first commit left open has since been answered and the docs
amended (second commit), so nothing in here is knowingly stale.

🤖 Generated with Claude Code

https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt

jcschaff and others added 3 commits August 19, 2026 15:20
@jcschaff @claude
docs(backlog): triage all 272 open issues into docs/backlog/
f833141 
A grooming pass over every open issue in this repo, cross-referenced against
project board #1. Proposals only - no issues, labels, or board fields were changed.

Structure: README indexes the set; 00-04 are the analysis (triage method, close
candidates, refinement list, board hygiene, epic map); 10-19 are ten thematic
groups. Every open issue appears in exactly one group table - verified: 271 rows
across the group docs plus #1032 in the epic map, no duplicates, no omissions.

Findings worth acting on:

- Board Priority/Importance polarity is undocumented and could not be determined
  from the data (r=0.84 with each other; the High Priority label overlaps only 8
  of 57 and spreads across the full range). Both readings are coherent and give
  opposite slates, so every table here is written polarity-neutral.
- 55 open issues are not on the board, and they skew recent and well-described:
  the 2026 SpringSaLaD grooming set, the field-viewer train, all six August
  infrastructure issues.
- 45 issues carry labels naming shipped releases; the current line is 8.0.27.01.
- 107 of 272 issues (39%) have a body under 200 chars; 73 are a July-2022 bulk
  import of a spreadsheet, ~34 of those with empty bodies.
- Four issues are marked Done on the board but still open; 14 close candidates
  in total, six verified against the working tree or git log.
- Four pairs of epics overlap, and five strategic decisions gate double-digit
  numbers of issues (04-epic-map.md).

Kept as one commit: the 16 documents are a single deliverable with dense
bidirectional cross-references, so splitting them would leave broken links in
the intermediate state.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt
@jcschaff @claude
docs(backlog): resolve the board scoring model - Priority = Importanc…
1ef1667 
…e + Simplicity

Jim identified that importance and difficulty together form the priority. Tested
against the board data and it holds exactly: 56 of 57 ranked issues satisfy
Priority = Importance + Simplicity, mean absolute error 0.09. No competing
formula gets above 15/57.

This resolves the ranking direction the first draft could not settle: higher
Priority = do sooner. Priority is a derived total, not an independent judgment,
which also explains the r=0.84 correlation with Importance that the earlier
draft misread as two opinions agreeing.

Three consequences now documented:

- #1495 is the single mismatch - stored Priority 5, but I=6 + Moderate(4) = 10.
  Recomputing moves it from mid-pack to near the top of the queue.
- Four issues (#1473, #1451, #1199, #191) have Importance scored but Priority
  never computed, so they sit in Pool and never appear in the ranked slate.
  #1473 and #1451 both compute to 12, tying the highest score on the board.
- Because ease is added rather than multiplied, a Byzantine(1) item caps at
  Priority 11 however important it is. That is why the accessibility work ranks
  low, and it is an argument for resourcing #1603 outside the queue rather than
  competing on a score it structurally cannot win.

Also corrects superlatives the first draft got wrong: #1384 holds the highest
Importance (10); #1199 is second at 9, and #194 is not the joint-highest.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt
@jcschaff @claude
docs(backlog): apply the board score corrections and refresh the tables
15aaecc 
Applied to project board #1 at Jim's instruction, after confirming the
Priority = Importance + Simplicity model:

  #1495  Priority 5 -> 10                  (I6 + Moderate(4); arithmetic had drifted)
  #1473  Priority - -> 12, Pool -> Queued  (I7 + Simple(5))
  #1451  Priority - -> 12, Pool -> Queued  (I7 + Simple(5))
  #1199  Priority - -> 11, Pool -> Queued  (I9 + Intricate(2))
  #191   Priority - ->  8, Pool -> Queued  (I6 + Intricate(2))

These are arithmetic corrections to the team's own model, not new judgments -
every input value was already on the board.

Verified against a fresh read after the edit: 61 issues now carry a Priority,
zero violate the formula, and nothing remains scored-but-unranked. Group tables
regenerated from post-edit board data; coverage re-checked at 271 rows plus
#1032, no duplicates or omissions.

The README no longer claims the pass changes nothing on GitHub, since it now
does; the exception is stated up front and scoped to these five score fields.

Flagged rather than silently accepted: #1199 is an epic with zero linked
children, so it is now queued as an empty container. Queuing it was done as
instructed and is trivially reversible - populating it or returning it to Pool
are both reasonable.

Still open: 53 issues have Simplicity but no Importance, so they remain
half-scored and cannot receive a Priority. The formula itself is still
undocumented on the board.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt
@jcschaff jcschaff mentioned this pull request Aug 19, 2026
Open
jcschaff and others added 2 commits August 19, 2026 16:10
@jcschaff @claude
docs(backlog): obsolescence sweep - check whether the code issues nam…
bdae114 
…e still exists

Ran tools/obsolescence-sweep.py over all 272 open issues against the working
tree, then confirmed every surviving finding by hand. Raw tool output is not
trustworthy alone; the false-positive modes are documented in the doc.

Headline, and the honest limit: only 58 of 272 issues name anything checkable -
a class, method, path, or library. The rest name nothing a machine can look up.
That is the same 39%-thin-body problem in another guise, and it is the ceiling
on automated obsolescence checking here.

Settled six issues:

- #366  seaborn is GONE from the tree (only trace is a transitive extras line in
        another package's lock file); #1472 independently records the Python
        plotting removal as COMPLETE. Two signals -> close candidate.
- #877  My earlier 'may be obsolete' guess was WRONG in the other direction.
        io.jhdf is present and ncsa.hdf is gone, so jHDF is now the SOLE HDF5
        reader and a JRE bug affecting it matters more, not less. Re-rank up.
- #1341 jlibsedml is VENDORED - 148 files in vcell-core at 3.0.0, no artifact in
        any pom. So this is a local patch we can just make, not an upstream ask.
- #1470 Same fact, opposite effect: there is no version to bump, so this is a
        fork-reconciliation job like #1978 proposes for JSBML, not an upgrade.
- #1636 Supplies the target version 02-needs-refinement.md flagged as missing:
        vendored BioNetGen 2.3.0, VERSION untouched since 2017-06-05, against
        upstream 2.9.3 (2025-04-21).
- #1637 NFSim is not in this repo - it is a vcell-solvers binary; upstream
        v1.14.3. Should move repos or say where the version lives.

Corrects three earlier claims in these docs that this sweep overturned (#877 and
#366 in 13-export-visualization.md, the jlibsedml framing in
11-standards-interop.md) and fills in 02-needs-refinement.md's open question on
#1636/#1637.

Still unverified and needing a person, not a script: #1384, #842, #1674, #1552 -
they name no code.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt
@jcschaff @claude
fix(tools): obsolescence sweep - case-insensitive resolution and an e…
8a46b20 
…mpty-index guard

Two bugs, the second worse than the first.

1. Case sensitivity (the reported one). #912 names SedmlJob.java; the file is
   SedMLJob.java, so the sweep called it missing and the issue looked obsolete.

   Fixed by adding a third outcome rather than just folding case. A reference that
   resolves only case-insensitively means the code EXISTS and the issue text is
   stale - that calls for correcting the issue, not closing it, which is a
   different action from 'the code is gone'. The tool now reports present /
   renamed / missing, and names what each stale reference actually resolves to.

   Also tightened path matching: a stem match across different extensions is not a
   match. 'experiment/outputs/temp/model.xml' was resolving to 'Model.java'.

2. Silent degradation (found while testing the first). Run from outside the repo,
   git ls-files returned nothing, the identifier index was empty, and every
   reference therefore looked missing - it cheerfully reported 42 issues with all
   references gone, output that reads as 'a sixth of the backlog is obsolete' and
   is pure artifact. It now refuses to run when the index looks empty. A sweep like
   this fails confidently by default, so the guard is not optional.

Also made the script runnable by anyone: the hardcoded scratchpad and checkout
paths are gone, it takes the issues JSON as an argument, and resolves the repo via
git rev-parse or VCELL_REPO.

After the fix: #912 is the only 'renamed' case and #1578 (which lives in
vcell-solvers) the only 'missing' one. Every substantive conclusion in
05-obsolescence-sweep.md is unchanged - seaborn still GONE, jhdf still PRESENT -
so no finding needed revisiting, only the false-positive table.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt
This was referenced Aug 19, 2026
Open
Open
Open
Closed
@jcschaff @claude
docs(backlog): apply the #366/#1341/#1470/#1636 issue updates
e618eda 
Carried out the four highest-confidence actions from the obsolescence sweep.

#366  CLOSED as not-planned. Three independent signals: seaborn appears only as
      an optional extras line belonging to networkx (poetry.lock:1126), nothing
      imports it anywhere, and the replacement exists as the Java package
      org.vcell.cli.run.plotting. Matches #1472's 'plotting done java side
      [COMPLETE]'. The closing comment carries the evidence and explicitly asks
      @CodeByDrescher to reopen if a live Python plotting path was missed, and
      notes the residual need (palettes for correlated series) would be a new
      issue against a different package.

#1341 Commented: jlibsedml is vendored (148 files in vcell-core at 3.0.0, no pom
      artifact), so this is a local patch, not an upstream request to wait on.

#1470 Commented: same fact, opposite effect - there is no version to bump, so
      this is fork reconciliation of the kind #1978 plans for JSBML.

#1636 Commented: vendored BioNetGen 2.3.0, VERSION untouched since 2017-06-05,
      against upstream 2.9.3 (2025-04-21) - 6 minor versions, ~8 years. Plus the
      two scoping facts: it is vendored Perl not a manifest entry, and a version
      change moves simulation results so it needs a validation plan. Notes that
      NFSim (#1637) is not in this repo at all.

Findings went in as COMMENTS, not body edits, on all three open issues - the
authors' words stay intact and the additions are attributable.

#877 was deliberately NOT applied: 're-rank upward' is a scoring judgment, not a
fact, so it needs a person.

Docs updated to match: the README no longer implies the pass leaves GitHub
untouched, and records that the backlog is now 271 open. The snapshot tables are
deliberately NOT regenerated - #366 still appears in 13-export-visualization.md,
annotated as closed, because these documents are dated evidence rather than a
live view.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kr8SbzXtwW3gMVUgMfDDt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jcschaff