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-learn, 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-learn to extract candidate Context Directive Records (CDRs) and compliances from the active session.
2. clarify⭐ (clarify phase) -> Invoke team-learn 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-learn 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-learn.

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 .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-learn for human review. Promotions route to action P — Promote to check (team-learn 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' state files (.factory-<orchestrator>-state.json) and evidence files. Identify patterns, recurring errors, or successful corrections.
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/workflow/memory.jsonl. 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-learn, 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-learn, change-*, and team-* skills are installed, and that the directives repo path is set in .adlc/init-options.json.