Discussion: Deprecate Learning Platform in Favor of RPI-Guided "Good First Issues"

[WilliamBerryiii]

Category: RFC / Architecture Decision
Scope: learning/ directory, GitHub issue workflow, hve-core RPI framework integration

---

Summary

Deprecate the standalone Learning Platform (learning/) and replace it with a sustainable, backlog-integrated model: a fixed percentage of GitHub issues are labeled good first issue and include embedded RPI (Research → Plan → Implement → Review → Discover) tutorial scaffolding from hve-core. Learning happens through real contribution, not a parallel content system.

---

Problem Statement

The current Learning Platform is a self-contained ecosystem of 50 katas, 5 learning paths, training labs, a skill assessment system, a catalog generator, a progress tracker, and contribution guidelines. While comprehensive, it carries structural costs:

1. Maintenance burden — 55+ content items require ongoing updates as the codebase evolves. Katas reference specific components, blueprints, and tooling versions that drift out of sync with src/ and blueprints/.

2. Parallel content system — The platform duplicates knowledge that already exists in component READMEs, instruction files (.github/instructions/), and copilot prompts (.github/prompts/). Contributors must maintain both the source-of-truth documentation and the learning content separately.

3. Disconnected from contribution — Completing a kata doesn't produce a real contribution. Learning and doing are separate activities, reducing the transfer of skills into actual project work.

4. Scaling friction — Adding a new component or blueprint doesn't naturally produce learning content. The learning platform depends on dedicated authoring effort with its own templates, review process, and tooling pipeline (Generate-LearningCatalog.ps1, path-manifest.json).

5. Onboarding gap — New contributors must discover the learning platform, install dependencies, run npm run docs, navigate to the learning section, complete an assessment, and then choose a path — before writing a single line of code against the actual repo.

---

Proposed Alternative

Replace the learning platform with RPI-guided good first issues — a model where learning is embedded directly in the GitHub backlog.

Core Mechanics

1. Fixed percentage target — Maintain a target percentage (e.g., 15-20%) of open issues labeled good first issue at any given time. This is enforced through sprint planning and backlog triage, not automation.

2. Embedded RPI scaffolding — Each good first issue includes a structured body with built-in guidance that maps to the hve-core RPI framework phases:

   ## Context
   Brief description of what this issue addresses and why it matters.
   
   ## Research Guidance
   - [ ] Read [component README](link) for background
   - [ ] Review [relevant instruction file](link) for conventions
   - [ ] Examine [existing patterns](link) in related components
   
   ## Implementation Guidance
   - [ ] Suggested approach and entry points
   - [ ] Key files to modify with line references
   - [ ] Expected output or behavior
   
   ## Review Criteria
   - [ ] Passes `npm run tf-validate` / `npm run tflint-fix-all` (or equivalent)
   - [ ] Follows conventions from `.github/instructions/`
   - [ ] Component README reflects changes (if applicable)
   
   ## RPI Agent Support
   Use the hve-core RPI agents for guided assistance:
   - `task-research` — Deep-dive into the problem space
   - `task-plan` — Generate an implementation plan
   - `task-implement` — Execute against the plan
   - `task-review` — Validate your changes
   - `rpi-agent` — Full autonomous workflow

3. Difficulty tiers via labels — Use existing GitHub label infrastructure to indicate complexity:

   • good first issue + difficulty: foundation — Minimal prior knowledge needed
   • good first issue + difficulty: intermediate — Requires component familiarity
   • good first issue + difficulty: expert — Cross-component or architectural scope

4. Self-guided with AI coaching — Contributors use hve-core agents (task-research, task-plan, task-implement, task-review) directly in VS Code instead of following static kata instructions. The RPI framework provides the same structured learning progression but against real work.

What This Replaces

Learning Platform Feature	Replacement
Katas (50 items)	good first issue issues with embedded guidance
Learning paths (5 paths)	Milestone-grouped issues with progressive difficulty labels
Skill assessment	Self-selection via difficulty labels; AI coaching via @task-research
Progress tracking	GitHub issue completion history
Catalog & path manifest	GitHub issue search and label filtering
Training labs	Larger good first issue items scoped as multi-step issues with sub-issues
Contributing guide (learning)	Standard repo CONTRIBUTING.md + issue template

---

Benefits

• Zero content drift — Issue guidance references live code paths and instruction files. When the codebase changes, stale issues surface naturally through triage.
• Every learning activity produces a real contribution — No throwaway exercises. Completed issues advance the project.
• Lower maintenance — No parallel content pipeline. Issue creation is part of normal backlog grooming.
• Natural onboarding funnel — New contributors find good first issue on GitHub, clone the repo, and start working with AI agent support immediately.
• RPI framework does the heavy lifting — The hve-core agents (task-research, task-plan, task-implement, task-review, rpi-agent) provide interactive, context-aware guidance that surpasses static written tutorials.
• Scales with the project — As new components and blueprints are added, associated good first issue items are created as part of normal development workflow.
• Backlog health — Maintaining a percentage of onboarding-friendly issues ensures the backlog stays accessible and well-decomposed.

---

Migration Plan

Phase 1: Issue Template & Label Setup

• Create a good first issue GitHub issue template with embedded RPI scaffolding sections
• Establish difficulty tier labels (difficulty: foundation, difficulty: intermediate, difficulty: expert)
• Define the target percentage and add it to sprint planning conventions

Phase 2: Seed Initial Issues

• Convert the highest-value katas into good first issue items with real scope against the current codebase
• Prioritize katas that align with existing backlog gaps or planned work
• Target: 15-20 well-crafted issues across all difficulty tiers

Phase 3: Deprecation

• Add a deprecation notice to learning/README.md pointing to the good first issue label filter
• Archive the learning/ directory (move or remove based on team preference)
• Remove learning platform tooling scripts (Generate-LearningCatalog.ps1, etc.)
• Update CONTRIBUTING.md to reference the new onboarding model

---

Open Questions

1. What is the right percentage target? 15-20% is a starting point. Should this vary by milestone or project phase?
2. Should any katas be preserved as standalone reference material? Some katas (e.g., AI Development Fundamentals, Copilot Modes) teach generic skills not tied to specific issues.
3. How do we measure onboarding effectiveness? The learning platform had skill assessments. Do we need a lightweight alternative, or is issue completion rate sufficient?
4. Should the issue template be enforced via GitHub Actions or remain a convention enforced through triage?
5. Timeline: What is the deprecation grace period before removing learning/?

---

References

• Current learning platform: learning/ (55 items across 10 kata categories, 5 paths, 3 training lab tracks)
• hve-core RPI Agent: hve-core/.github/agents/hve-core/rpi-agent.agent.md
• hve-core task agents: @task-research, @task-plan, @task-implement, @task-review
• RPI prompt: hve-core/.github/prompts/hve-core/rpi.prompt.md
• Repo instruction files: .github/instructions/ (terraform, bicep, shell, python, csharp)