/factory-learn

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 tha