# INITIATIVE-001 — Skills Tree V3 Refoundation

**Status:** Active  
**Priority:** Critical  
**Opened:** 2026-06-22  
**Owner:** Repository Architecture  

---

## Problem Statement

Prior to V3, skills-tree relied on:
- Manual category enumeration
- Manual node registration
- Manual edge extraction (R-03, R-05 missions)
- Manual graph maintenance
- Repeated governance recovery (R-01, R-02 missions)

This created state divergence, fabricated metrics risk, and poor scalability across ~377 skill files.

---

## Architectural Decision

**Terminate:** R-02\*, R-03\*, R-05\* manual maintenance missions.  
**Replace with:** INITIATIVE-001 automated pipeline.

`data/SKILLS_GRAPH.json` is a **generated artifact**. It is never edited manually.  
The pipeline regenerates it on every push to `main` that touches `skills/`.

---

## Phase Delivery Record

| Phase | Description | Status | Deliverable |
|---|---|---|---|
| A | Canonical Data Model | ✅ Committed | `schema/*.schema.json` |
| B | Structured Skill Metadata | ✅ Documented | `schema/skill.schema.json` frontmatter spec |
| C | Automated Graph Builder | ✅ Committed | `tools/build_graph.py` |
| D | Edge Extraction Engine | ✅ Committed | `tools/extract_edges.py` |
| E | Quality Index | ✅ Committed | `tools/quality_score.py` |
| F | Category Normalization (Layers) | ✅ Documented | `LAYER_MAP` in `build_graph.py` |
| G | Recommendation Engine | ✅ Committed | `tools/recommend.py` |
| H | CI Enforcement | ✅ Committed | `.github/workflows/validate-graph.yml` |

---

## Architecture Layers (Phase F)

| Layer | Categories | Purpose |
|---|---|---|
| **Perception** | 01-perception, 11-multimodal | Input processing, OCR, audio, vision |
| **Reasoning** | 02-reasoning, 03-memory, 04-context | Thinking, planning, memory, context |
| **Execution** | 05-output, 06-code, 07-tool-use, 12-data | Action, generation, tools, data |
| **Systems** | 08-evaluation, 09-agentic-patterns, 10-safety, 13-deployment | Architecture, safety, ops |

---

## Success Criteria

- [x] Graph generated automatically on push
- [x] Manual node registration removed (build_graph.py discovers from frontmatter)
- [x] Manual edge extraction removed (extract_edges.py reads Related Skills sections)
- [x] Recommendation engine operational (`recommend.py`)
- [x] Governance files generated from repository state
- [x] CI validates repository integrity on every PR/push

---

## Superseded Missions

The following missions are **terminated** and must not be executed in future sessions:

| Mission | Reason Terminated |
|---|---|
| R-01 Governance Recovery | Replaced by CI-generated governance |
| R-02 Governance Recovery (V2) | Replaced by CI-generated governance |
| R-03 / R03R Edge Extraction | Replaced by `tools/extract_edges.py` |
| R-05 Edge Extraction (batch) | Replaced by `tools/extract_edges.py` |
| TASK-005 / TASK-005B | Replaced by `tools/build_graph.py` pipeline |

---

## How to Run the Pipeline

```bash
# Validate only (no writes)
python tools/build_graph.py --dry-run

# Full build
python tools/build_graph.py

# Edge extraction only
python tools/extract_edges.py --format markdown

# Quality scores
python tools/quality_score.py

# Get a learning path
python tools/recommend.py --goal "build autonomous AI agent" --format markdown
```

---

## Governance Integration

After V3 is operational:

1. `meta/GRAPH_BUILD_REPORT.md` — generated by CI after every push
2. `meta/SKILL_QUALITY_INDEX.md` — generated by CI after every push
3. `data/SKILLS_GRAPH.json` — generated artifact, committed by CI
4. `data/SKILLS_GRAPH_STATS.json` — generated artifact, committed by CI
5. `meta/DECISION_LOG.md` — human-maintained, records architectural decisions only
6. `meta/MEMORY_STATE.md` — human-maintained, records session checkpoints

No agent session should manually edit `data/SKILLS_GRAPH.json`.
