Skip to content

docs: add current-state-inventory-priority.md (priority by downstream leverage)#9

Merged
rafael5 merged 1 commit into
mainfrom
docs/current-state-inventory-priority
May 11, 2026
Merged

docs: add current-state-inventory-priority.md (priority by downstream leverage)#9
rafael5 merged 1 commit into
mainfrom
docs/current-state-inventory-priority

Conversation

@rafael5

@rafael5 rafael5 commented May 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Supplements `AI-discoverability-plan.md` §3.4. §3.4 was authored when no repo shipped the Phase-0 contract; with tier-1 + tier-2 onboarded (6 of 9 repos as of 2026-05-10), that table is stale as a priority guide.

This doc reframes priority around downstream dependents — not by ease of shipping.

What it adds beyond §3.4

§3.4 (original) This doc
"Do tier-1 → tier-2 → tier-3" "Do the items that unblock the most others"
Snapshot when nothing was done Snapshot as of 2026-05-10 (tier-1 + tier-2 ✅, tier-3 pending)
No dependency analysis ASCII dependency graph + ranked downstream counts
No specific "next move" Concrete recommendation: ship P1-A as a single coherent PR

Headline ranking

Rank Item Downstream items unblocked
1 P1-A — schemas + task_index split 6 (P1-B, P1-D, P3-handshake, P4-mcp, P5-schema-version, MCP ↔ catalog story)
2 P1-B — build-catalog + validate-catalog 5
3 P1-D — make + CI wiring 3
4 T3-* onboarding (×3) 0 formal — but timing leverage if done parallel with P1-B
5 P1-C — llms.txt 1
6–9 recipes / MCP / continuous enforcement 0 (terminal but valuable)

§6.4 The "easy first" trap, explicitly

Spending a week on three easy PRs (P1-C + two T3 onboardings) leaves you with no `build-catalog.py`, no tightened schemas, and the catalog still hand-curated and drift-prone. The same week spent on P1-A unblocks six downstream items, after which the easy work can run in parallel against the new contract and pick itself up mechanically.

§7 Recommended next move

Ship P1-A as a single coherent PR in `.github` — schemas tightened, `task_index.json` split, `tools.json` slimmed, `schema-changelog.md` created (folds P1-X). Then kick off P1-B, P1-C, and T3-* in parallel.

Test plan

  • `make check-docs-prose` green (doc is .md under `docs/`)
  • Self-contained — every claim in the doc is sourced (parent plan §3.4 / §7, phase0-plan, phase1-plan, or canonical validator output)

Supplements AI-discoverability-plan.md §3.4. §3.4 was authored when no
repo shipped the Phase-0 contract; with tier-1 + tier-2 onboarded
(6 of 9 repos as of 2026-05-10), that table is stale as a priority
guide.

This doc reframes priority around the actual remaining work and
ranks it by *downstream dependents* — not by ease of shipping.

Structure:
- §2 Current-state inventory (per-repo Phase-0 contract status)
- §3 Outstanding work catalogued from parent plan §7 + phase1-plan.md
- §4 Dependency graph (ASCII; shows what blocks what)
- §5 Priority ranking by downstream-leverage (P1-A ranks #1 with 6
  downstream items; tier-3 onboarding ranks #4 despite being
  "easy" because it doesn't unblock anything)
- §6 Recommended execution order — single-threaded sequence + which
  items to parallelize when bandwidth allows
- §6.4 explicit "easy first" trap: ships three quick PRs, leaves
  nothing unblocked
- §7 Concrete recommended next move: ship P1-A as a single coherent
  PR (cuts the longest dependency chain in front of the entire
  Phase 1 + 3 + 4 stack)
- §8 How to keep the doc in sync (read-then-act discipline)

Source files referenced (all on main):
- AI-discoverability-plan.md §3.4 — original tier-based framing
- phase0-plan.md — completed
- phase1-plan.md — to-do, Track A-D layout matches §3-5 here

Prose-only gate (make check-docs-prose) green: doc is .md under docs/.
@rafael5 rafael5 merged commit 71940bb into main May 11, 2026
1 check passed
@rafael5 rafael5 deleted the docs/current-state-inventory-priority branch May 11, 2026 03:10
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.

1 participant