docs: score backlog and integrate LLM features into roadmap

[carlos-alm]

Summary

• Score all 20 backlog features across zero-dep, foundation-aligned, problem-fit (1-5), and breaking columns in BACKLOG.md
• Reorganize backlog into 3 priority tiers: Tier 1 (zero-dep + foundation-aligned), Tier 2 (needs deps), Tier 3 (needs foundation exception) — ordered by problem-fit with breaking changes penalized to end of each block
• Integrate llm-integration.md features into ROADMAP.md across 6 new sub-phases:
  • 3.4 Build-time semantic metadata (side_effects, complexity_notes, risk_score)
  • 3.5 Module summaries and naming conventions
  • 4.4 LLM-narrated graph queries (flow tracing, upstream analysis, effect analysis)
  • 4.5 Onboarding and navigation tools (entry points, reading order, change planning)
  • 6.2 Expanded with LLM-enhanced PR review (risk labels, review focus, test gap detection)
  • 6.3 Visual impact graphs for PRs (CI automation, LLM annotations, churn overlay)
  • 7.5 Refactoring analysis (split, extraction, signature, hotspots, boundaries)
  • 7.6 Auto-generated docstrings
• Updated overview table, dependency graph, verification strategy, and integration test

Test plan

• Verify roadmap/BACKLOG.md renders correctly (tier headers, tables, checkmarks)
• Verify roadmap/ROADMAP.md renders correctly (new sub-sections, tables, cross-references)
• Confirm all 20 backlog features present with no content loss
• Confirm all llm-integration.md features accounted for in the roadmap
• Validate internal links (llm-integration.md references) resolve correctly

[claude]

Claude finished @carlos-alm's task —— View job

---

Root Cause Analysis

Problem Being Solved: The backlog was previously unscored and unsorted, making it difficult to prioritize development work. All 20 features had blank assessment columns, making strategic planning impossible.

Why This Approach: The PR systematically evaluates each feature against FOUNDATION.md principles and reorganizes them into actionable tiers. This creates a clear development roadmap based on zero-dependency capabilities, foundation alignment, and problem-fit scoring.

Risk Assessment: Very low risk - documentation-only change with no code modifications.

Critical Concerns

PR Description Inaccuracy: The PR description claims to fix track-moves.sh hook issues, but no such changes are present in the commit. Only roadmap/BACKLOG.md was modified. This creates confusion about what was actually delivered.

Quality Assessment

Strengths:

• ✅ All 20 features preserved with accurate content
• ✅ Scoring methodology follows FOUNDATION.md principles correctly
• ✅ Tier organization creates actionable prioritization (15 features in Tier 1, 2 in Tier 2, 3 in Tier 3)
• ✅ Problem-fit scores align with core goal of reducing agent token waste/hallucinations
• ✅ Zero-dep vs dependency classification is accurate
• ✅ Breaking changes properly flagged and penalized within tiers

Spot checks passed:

• Feature Bump tree-sitter-javascript from 0.23.1 to 0.25.0 #4 (Node classification) - 5/5 problem-fit ✓ (directly reduces orientation tokens)
• Feature ci: add license compliance workflow and CI Testing Pipeline gate #10 (HTML visualization) - Tier 3 ✓ (violates Principle 8: no GUI)
• Feature feat: Rust core engine via napi-rs (Phase 1) #8 (LLM provider integration) - Tier 2 ✓ (foundation-aligned but needs deps)
• Feature feat!: granular node types, GitNexus comparison, PreToolUse hooks #14 (Dataflow analysis) - Breaking=Yes ✓ (would change edge schema/API)

Minor issues:

• Table formatting is clean and GitHub will render correctly
• Scoring guide at bottom provides clear criteria for future assessments

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE WITH CONDITIONS
• Reasoning: Excellent documentation work that creates a clear, principled development roadmap. The scoring methodology is sound and execution is thorough. Only issue is the misleading PR description claiming hook fixes that aren't present. This should be corrected in the PR description or commit message, but doesn't affect the quality of the actual changes delivered.

Conditions for approval:

1. Update PR description to remove mention of track-moves.sh fix, OR
2. Explain why the hook fix was mentioned but not included

---

[greptile-apps]

Greptile Summary

Scores all 20 backlog features and reorganizes them into 3 priority tiers based on zero-dep + foundation-alignment criteria. Tier 1 contains 15 features (14 non-breaking + 1 breaking), Tier 2 has 2 foundation-aligned features requiring dependencies, and Tier 3 has 3 features not aligned with FOUNDATION.md principles. Within each tier, features are ordered by problem-fit score (1-5) descending, with breaking changes penalized to the end.

• All 20 original features preserved with no content loss
• Scoring aligns with FOUNDATION.md principles (P1: always-current graph, P4: zero-cost core, P5: embeddable-first, P8: honest scope)
• Includes comprehensive scoring guide for future prioritization sessions
• The track-moves.sh hook fix mentioned in the PR description was implemented in parent commit cfe633b

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only change with complete feature preservation, logical tier organization, and accurate scoring against foundation principles
• No files require special attention

Important Files Changed

Filename	Overview
roadmap/BACKLOG.md	Reorganized 20 backlog features into 3 priority tiers with complete scoring (zero-dep, foundation-aligned, problem-fit, breaking)

_{Last reviewed commit: 638afcb}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review: docs: score backlog and reorganize into priority tiers

Todo List

• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity Check
• Phase 4: Code Quality Assessment
• Final Assessment & Rating

Root Cause Analysis

Problem Being Solved: The backlog was previously unscored and unsorted, making strategic prioritization impossible. All 20 features had blank assessment columns (zero-dep, foundation-aligned, problem-fit, breaking), providing no guidance for development planning.

Why This Approach: Systematic evaluation against FOUNDATION.md principles creates an objective, actionable roadmap. The 3-tier organization (15 zero-dep foundation-aligned features in Tier 1, 2 foundation-aligned but requiring deps in Tier 2, 3 non-foundation-aligned in Tier 3) provides clear development priorities.

Risk Assessment: Very low risk - documentation-only change with no code modifications.

Critical Concerns

PR Description Inaccuracy

The PR description claims to "Fix: add track-moves.sh hook to log mv/git mv/cp destinations" but no such changes exist in this commit. The track-moves.sh fix was actually implemented in parent commit cfe633b. This creates confusion about deliverables.

Quality Assessment

Strengths:

• ✅ Complete feature preservation: All 20 original features retained with accurate content
• ✅ Sound scoring methodology: Evaluations align with FOUNDATION.md principles (P1: always-current, P4: zero-cost core, P5: embeddable-first, P8: honest scope)
• ✅ Logical tier organization: Creates clear prioritization (Tier 1: 15 features, Tier 2: 2 features, Tier 3: 3 features)
• ✅ Accurate problem-fit scoring: Scores properly reflect core goal of reducing agent token waste/hallucinations
• ✅ Correct zero-dep classification: Features requiring runtime deps properly marked
• ✅ Breaking changes handled: Properly flagged and penalized within tiers

Spot Check Validation:

• Feature Bump tree-sitter-javascript from 0.23.1 to 0.25.0 #4 (Node classification): 5/5 problem-fit ✓ - directly reduces agent orientation tokens
• Feature ci: add license compliance workflow and CI Testing Pipeline gate #10 (HTML visualization): Tier 3 ✓ - violates Principle 8 (GUI conflicts with "honest scope")
• Feature feat: Rust core engine via napi-rs (Phase 1) #8 (LLM provider integration): Tier 2 ✓ - foundation-aligned but needs dependencies
• Feature feat!: granular node types, GitNexus comparison, PreToolUse hooks #14 (Dataflow analysis): Breaking=Yes ✓ - would change edge schema/API

Documentation Quality:

• Clear scoring guide provides objective criteria for future prioritization
• Table formatting will render correctly on GitHub
• Tier descriptions explain prioritization logic
• Within-tier ordering (problem-fit descending, breaking penalized) is consistently applied

Minor Observations:

• No content loss from original backlog
• Assessment methodology is transparent and repeatable
• Scoring aligns with README's core problem statement

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE WITH CONDITIONS
• Reasoning: Excellent documentation work that transforms an unactionable backlog into a clear, principled development roadmap. The scoring methodology is sound, execution is thorough, and all features are properly preserved. The only issue is the misleading PR description claiming hook fixes that aren't present.

Conditions for approval:

1. Update PR description to remove mention of track-moves.sh fix, OR
2. Add a note clarifying that the hook fix was implemented in parent commit cfe633b

This creates a valuable strategic planning document that will guide development decisions effectively.

---