---
name: factory-learn
description: Use when coordinating continuous improvement loops (team-levelup + change + evals feedback + cleanup) targeting team-ai-directives — includes build-to-delete pruning and promote-to-check.
disable-model-invocation: true
---

# factory-learn

## What this skill does

`factory-learn` orchestrates the continuous improvement learning loop of the software factory. It coordinates individual learning-related skills (`team-init`, `team-levelup`, `change-init`, `change-clarify`, `change-publish`, `team-repair`, `evals-analyze`) to transition draft directives into verified, published, and minimal team context assets.

It operates as a **Kind-A DAG orchestrator** in alignment with the shared executor engine contract in `factory-mission/references/executor.md`.

---

## When to use

- You want to extract and compile hard-won session learnings into your team's centralized `team-ai-directives` repository.
- You want to mine git commit history to capture the rationale (ChDRs) behind past reverts and hotfixes.
- You want to run "Build to Delete" (Harness Decay checks) to prune redundant rules.

**When NOT to use**:
- For product-level specification or development (use `factory-product` or `factory-mission` instead).
- If the team directives repository is completely unconfigured (run `/team-setup` first).

---

## Lifecycle DAG & Step Resolution

`factory-learn` implements a **fixed named-skill DAG** (`fixed` step resolution):

### Session Learnings Route (default on session-end)
1. **`specify`** (`generate` phase) -> Invoke `team-levelup` to extract candidate Context Directive Records (CDRs) and compliances from the active session.
2. **`clarify`⭐** (`clarify` phase) -> Invoke `team-levelup` to review pending CDRs. Enforces the **evals-regression gate** (running the compliance goldset as the `verify` sub-phase to ensure no quality degradation).
3. **`publish`** (`build` phase) -> Invoke `team-levelup` to package accepted CDRs, index them, and compile a draft PR targeting the `team-ai-directives` repository.
4. **`prune`** (`analyze` phase) -> Runs the cleanup bot over the directive store to detect and propose deprecations of superseded, contradictory, or stale rules. Deprecations feed back to `team-levelup`.

### Historical Mining Route (brownfield)
1. **`init`** (`generate` phase) -> Invoke `change-init` to mine git history and issue trackers for Change Decision Records (ChDRs).
2. **`clarify`⭐** (`clarify` phase) -> Invoke `change-clarify` to run interactive provenance reviews on mined claims.
3. **`publish`** (`build` phase) -> Invoke `change-publish` to promote accepted ChDRs into `docs/adlc/memory/chdr/` and regenerate indices.

### Maintenance & Build-to-Delete Route (periodic)
1. **`verify`** (`verify` phase) -> Run `team-repair --build-to-delete`. Re-runs goldset evals with rules temporarily disabled. Two questions per rule:
   - **Build-to-delete**: if the model passes without the rule, the rule is flagged as redundant.
   - **Promote-to-check** (deterministic-checks-first, EVAL-010): if a deterministic check (unit test / binary grader / pre-commit hook / lint rule / CI job) can mechanically enforce the rule, flag it as a promotion candidate — pay once for the check instead of re-injecting a fuzzy rule into every session.
2. **`clarify`⭐** -> Proposes the redundant rule's deprecation and the mechanical rule's promotion to `team-levelup` for human review. Promotions route to action **P — Promote to check** (team-levelup Phase 2b); once the check exists and runs in CI, the CDR is deprecated or reduced to a thin pointer. Both proposals publish as `findings`.

### Workflow Retrospective Route
Runs periodically or on-demand to analyze past runs of other factory skills (e.g. `factory-mission`, `factory-product`) and generate workflow memories:
1. **`analyze`** (`analyze` phase) -> Scan completed/failed runs' shared state (`.adlc/workflows/runs/<run_id>/state.json` via `adlc-cli workflow status`) and evidence files. Identify patterns, recurring errors, or successful corrections.
   - Also sweep `.adlc/drafts/{adr,pdr,chdr,cdr,evals}/` for unclarified entries (frontmatter/heading status proposed/discovered/draft); surface each as a finding (Draft ID + type + age), independent of whether session_end/file_edited hooks ever fired.
2. **`clarify`⭐** -> Present proposed memories (active vs tentative) to the user (in gated/hybrid modes) or auto-approve (in autonomous mode).
3. **`publish`** (`build` phase) -> Write approved memories to `.adlc/workflows/memory.jsonl` (workspace-global). Memories carry weights and use counts; stale or counter-productive memories are automatically archived.

---

## Shared Executor Overrides

`factory-learn` overrides the shared executor engine primitives as follows:

1. **Publish Target**: Fixed to `external-repo`. Opens or updates a draft pull request on the configured `team-ai-directives` repository. Since the publish target is a PR on the directives repo, the comment bus operates on that PR — step outputs (decisions, findings) are published as marker comments on the directives PR.
2. **Output Types**: Steps use the following `output_type` assignments:
   - `specify`/`init` → `draft` (CDR/ChDR drafts stay in `.adlc/drafts/`, not published to comment bus)
   - `clarify`⭐ → `decision` (accepted/rejected CDR/ChDR list published to comment bus on the directives PR)
   - `publish` → `artifact-ref` (PR URL reference published, content stays on disk)
   - `prune`/`verify` → `findings` (redundancy/deprecation report published to comment bus)
3. **Feedback Loop Ingestion**: Automatically consumes the output of `evals-analyze` (when an application test fails due to specification issues, `evals-analyze` automatically routes to `team-levelup`, which triggers this orchestrator).
4. **Supervision Default**: `hybrid`. Human gates are hard-enforced at `clarify`⭐ (approval of CDR/ChDR entries) and at final PR creation.
5. **Pre-flight Check**: Verifies that `team-levelup`, `change-*`, and `team-*` skills are installed, and that the directives repo path is set in `.adlc/init-options.json`.