improve-phase-1-collect-gather-session-signals

# Phase 1: COLLECT — Gather Session Signals (+6)

## Phase 1: COLLECT — Gather Session Signals


Scan these data sources for improvement candidates:

1. `.Codex/state/pending-reviews/memory-updates.jsonl` — memory candidates
2. `.Codex/state/pending-reviews/insights.jsonl` — insight candidates
3. `.Codex/state/pending-reviews/errors.jsonl` — error patterns
4. `.Codex/state/pending-reviews/skill-candidates.jsonl` — skill gaps
5. `.Codex/state/corrections/.recent_edits` — correction patterns
6. `.Codex/state/accumulator.json` — aggregated metrics
7. `.Codex/state/patterns/` — patterns from `/reflect`
8. `.Codex/state/pending-reviews/ecosystem-review.jsonl` — ecosystem health signals (from stop hook)
9. Current session context — what was learned in THIS session


## Phase 2: CLASSIFY — Route Improvements to Targets


| Signal Type | Target | Example |
|---|---|---|
| Institutional knowledge | `.Codex/memory/KNOWLEDGE.md` | "OrcaWave .frequencies returns Hz" |
| Domain-specific lesson | `.Codex/memory/<topic>.md` | "AQWA needs QPPL DIFF for diffraction" |
| Repeated correction | `.Codex/rules/*.md` | "Always validate freq order" |
| Skill gap / new capability | `.Codex/skills/**/ (create)` | "No skill for PDF table extraction" |
| Skill correction | `.Codex/skills/**/ (enhance)` | "Polars skill missing lazy frame pattern" |
| Underperforming skill | `.Codex/skills/**/ (deprecate)` | "Skill never used in 90 days, superseded" |
| Cross-session pattern | `AGENTS.md` Core Rules | "Batch operations reduce errors" |
| Resource drift | `AGENTS.md` Resource Index | "New agent in agents/devops/" |
| Documentation gap | `.Codex/docs/` | "Orchestrator pattern needs update" |
| Ecosystem health signal | Phase 3 review queue | "Skill sprawl: 350+ active skills" |
| Memory bloat signal | Phase 3 review queue | "MEMORY.md exceeds 200 lines" |


## Phase 3: ECOSYSTEM REVIEW — Structural Health Assessment


Assess the overall health of ecosystem files and recommend reallocation. This phase is fed by signals from the `ecosystem-health-check.sh` stop hook AND by scanning the filesystem directly.

**Data sources:**
1. `.Codex/state/pending-reviews/ecosystem-review.jsonl` — automated health check signals
2. Direct filesystem scan of `.Codex/skills/`, `.Codex/memory/`, `.Codex/rules/`

**Checks performed:**

| Check | Signal | Action |
|---|---|---|
| **Stale skills** | No session usage in 90+ days (via `last_used` in frontmatter) | Flag for deprecation review |
| **Index quality** | Skills missing `capabilities:`, `tags:`, or `related:` frontmatter | Flag for metadata enrichment |
| **Skill overlap** | 2+ skills with >70% description similarity | Flag for consolidation |
| **Memory bloat** | Any `.md` >200 lines | Recommend split into topic files |
| **Memory overlap** | Same topic in repo + user memory | Recommend single source of truth |
| **Thin categories** | Category with only 1 skill | Consider merging into parent |
| **Stale signals** | >50 unprocessed signals in pending-reviews/ | Warn about signal backlog |
| **Stub micro-skills** | Stage micro-skill file < 15 lines | Flag as enhancement candidate — stubs provide no guidance at stage entry |

> **Note on raw count thresholds**: Total skill count and per-category count limits
> (previously 350/50) have been removed. A large, well-indexed skill library is not
> a problem — stale and unreferenced skills are. Staleness detection requires the
> knowledge graph (WRK-205: `SKILLS_GRAPH.yaml` + `capabilities:`/`requires:`/`see_also:`
> frontmatter) to be effectively maintained. If the index is sparse, staleness signals
> will be noisy — assess index quality first.

**Knowledge graph maintenance** (when `SKILLS_GRAPH.yaml` exists — WRK-205):
- For any skill created or enhanced this session: verify it appears in `SKILLS_GRAPH.yaml`
- For any new relationship surfaced (A composes B, A requires B, A is alternative to B): add edge to graph
- For each new/enhanced skill: check that existing related skills have it in their `related_skills:` frontmatter (bidirectional linking); add missing links
- Update `last_used` timestamp in frontmatter for any skill loaded this session
- Flag skills missing `capabilities:`, `requires:`, or `see_also:` blocks for metadata enrichment

> **Prerequisite**: Graph maintenance only runs when `SKILLS_GRAPH.yaml` exists at `.Codex/skills/`. Skip silently if absent — WRK-205 implements the graph.

**Proactive skill discovery** (when `SKILLS_GRAPH.yaml` exists — WRK-205 + WRK-215):

Four checks are run to actively surface gaps — not just react to session signals:

| Check | Trigger | What it finds |
|-------|---------|---------------|
| Broken `see_also:`/`requires:` refs | Every `/improve` run | Skills referenced in frontmatter but no matching SKILL.md exists = gap |
| WRK-domain coverage | Weekly `/reflect` | Active WRK `tags:`/`module:` with no matching skill domain = under-skilled domain |
| Enhancement priority queue | Weekly `/reflect` | Skills with empty `capabilities:` AND `last_used` within 30 days = high-priority stubs |
| Domain saturation heatmap | `/improve --scope skills --audit` | WRK-items ÷ skills per domain ratio — low ratio = under-skilled domain |

**Broken-ref scan (runs every session):**
1. For each SKILL.md frontmatter: extract all `see_also:` and `requires:` values
2. For each value: check that a SKILL.md exists at the referenced path
3. Any broken reference → emit gap candidate to `.Codex/state/pending-reviews/skill-candidates.jsonl`
4. Dedup: only emit each gap once per 7 days (keyed by target path + date week)

**Enhancement priority queue (weekly, via `/reflect`):**
- Rank criteria: `see_also:` reference frequency (most-referenced-by-other-skills) as primary; `last_used` recency as tiebreaker
- Output: top-5 enhancement candidates appended to `.Codex/state/pending-reviews/skill-candidates.jsonl` with `type: enhancement`

**Domain saturation heatmap (on-demand: `/improve --scope skills --audit`):**
- For each skill domain (using WRK-205 category indexes): count skills
- For each domain: count active WRK items with matching `module:` or `tags:`
- Compute ratio; flag domains where ratio < 0.5 (more than 2 WRK items per skill)
- Print summary table to stdout; do not write to state files

> **Prerequisite**: All proactive discovery checks skip silently when `SKILLS_GRAPH.yaml` is absent.
> Log: "Skill discovery deferred — WRK-205 graph not yet built."

**Outputs:**
- List of consolidation recommendations (skill merges, memory splits)
- List of new skill candidates (gaps identified from session patterns)
- Responsibility reallocation suggestions (e.g., "move X from memory to rules")
- Knowledge graph updates: edges added, `last_used` timestamps written, missing links added
- Metrics: total_skills, archived_ratio, avg_category_size, memory_total_lines

**Decision rules:**
- Consolidation: Only recommend if both skills have been loaded in same session 3+ times
- New skills: Only when pattern seen 3+ sessions AND no existing skill covers it
- Reallocation: Only when content clearly belongs to a different target (e.g., repeated correction → rules, not memory)


## Phase 4: GUARD — Safety Checks Before Writing (incl. ecosystem review outputs)


1. **Size guards**:
   - AGENTS.md: 4KB budget
   - KNOWLEDGE.md: 200-line limit
   - Rules files: 400-line max per file
   - SKILL.md files: 400-line max

2. **Dedup check**: Read target file, verify improvement doesn't already exist

3. **No-clobber rule**: If target file has uncommitted changes, skip it

4. **Skill lifecycle gates**:
   - **Create**: Only when no existing skill covers the capability (search first)
   - **Deprecate**: Only when unused for 90+ days AND superseded by another skill
   - **Archive**: Move deprecated skills to `.Codex/skills/_archive/` (never delete)


## Phase 5: APPLY — Write Improvements


**AGENTS.md**: Resource Index scan, Core Rules for patterns confirmed 3+ sessions. Use Edit tool.

**Rules files** (`.Codex/rules/*.md`): Add examples from real corrections. Append to sections, never restructure.

**Repo memory** (`.Codex/memory/`): Add debugging lessons, tool conventions, API quirks. Use env var placeholders for paths. Create new topic file if section exceeds 10 entries.

**Skills** (`.Codex/skills/**/*.md`) — FULL LIFECYCLE:
- **Enhance**: Add examples, fix instructions from corrections
- **Create**: New SKILL.md when repeated pattern has no matching skill
- **Deprecate**: Add deprecation notice when unused 90+ days
- **Archive**: Move to `_archive/` with reason and date

**Docs** (`.Codex/docs/`): Update stale references, add missing documentation.


## Phase 6: LOG — Record Changes


Write to `.Codex/state/improve-changelog.yaml`:
- Timestamp, changes list with file/action/diff_summary
- Skills lifecycle metrics: created/enhanced/deprecated/archived counts
- Ecosystem health metrics: total_skills, memory_lines, consolidation_count, reallocation_count
- signals_processed, changes_applied, signals_skipped (with reason)


## Phase 7: CLEANUP — Mark Signals Consumed


Move processed signals from `pending-reviews/*.jsonl` to archive so they aren't reprocessed.