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-runbook/references/executor.md.
Requires: the factory-runbook skill (provides the shared executor contract): adlc-cli skills add tikalk/adlc-team-skills --skill factory-runbook
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-intent 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)
specify (generate phase) -> Invoke team-levelup to extract candidate Context Directive Records (CDRs) and compliances from the active session.
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).
publish (build phase) -> Invoke team-levelup to package accepted CDRs, index them, and compile a draft PR targeting the team-ai-directives repository.
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)
init (generate phase) -> Invoke change-init to mine git history and issue trackers for Change Decision Records (ChDRs).
clarify⭐ (clarify phase) -> Invoke change-clarify to run interactive provenance reviews on mined claims.
publish (build phase) -> Invoke change-publish to promote accepted ChDRs into docs/adlc/memory/chdr/ and regenerate indices.
Maintenance & Build-to-Delete Route (periodic)
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.
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-intent) and generate workflow memories:
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.
clarify⭐ -> Present proposed memories (active vs tentative) to the user (in gated/hybrid modes) or auto-approve (in autonomous mode).
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:
- 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.
- 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)
- 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).
- Supervision Default:
hybrid. Human gates are hard-enforced at clarify⭐ (approval of CDR/ChDR entries) and at final PR creation.
- 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.
1---2name: factory-learn3description: 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.4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/tikalk/factory-learn7---89# factory-learn1011## What this skill does1213`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.1415It operates as a **Kind-A DAG orchestrator** in alignment with the shared executor engine contract in `factory-runbook/references/executor.md`.1617**Requires:** the `factory-runbook` skill (provides the shared executor contract): `adlc-cli skills add tikalk/adlc-team-skills --skill factory-runbook`1819---2021## When to use2223- You want to extract and compile hard-won session learnings into your team's centralized `team-ai-directives` repository.24- You want to mine git commit history to capture the rationale (ChDRs) behind past reverts and hotfixes.25- You want to run "Build to Delete" (Harness Decay checks) to prune redundant rules.2627**When NOT to use**:28- For product-level specification or development (use `factory-intent` or `factory-mission` instead).29- If the team directives repository is completely unconfigured (run `/team-setup` first).3031---3233## Lifecycle DAG & Step Resolution3435`factory-learn` implements a **fixed named-skill DAG** (`fixed` step resolution):3637### Session Learnings Route (default on session-end)381. **`specify`** (`generate` phase) -> Invoke `team-levelup` to extract candidate Context Directive Records (CDRs) and compliances from the active session.392. **`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).403. **`publish`** (`build` phase) -> Invoke `team-levelup` to package accepted CDRs, index them, and compile a draft PR targeting the `team-ai-directives` repository.414. **`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`.4243### Historical Mining Route (brownfield)441. **`init`** (`generate` phase) -> Invoke `change-init` to mine git history and issue trackers for Change Decision Records (ChDRs).452. **`clarify`⭐** (`clarify` phase) -> Invoke `change-clarify` to run interactive provenance reviews on mined claims.463. **`publish`** (`build` phase) -> Invoke `change-publish` to promote accepted ChDRs into `docs/adlc/memory/chdr/` and regenerate indices.4748### Maintenance & Build-to-Delete Route (periodic)491. **`verify`** (`verify` phase) -> Run `team-repair --build-to-delete`. Re-runs goldset evals with rules temporarily disabled. Two questions per rule:50 - **Build-to-delete**: if the model passes without the rule, the rule is flagged as redundant.51 - **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.522. **`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`.5354### Workflow Retrospective Route55Runs periodically or on-demand to analyze past runs of other factory skills (e.g. `factory-mission`, `factory-intent`) and generate workflow memories:561. **`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.57 - 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.582. **`clarify`⭐** -> Present proposed memories (active vs tentative) to the user (in gated/hybrid modes) or auto-approve (in autonomous mode).593. **`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.6061---6263## Shared Executor Overrides6465`factory-learn` overrides the shared executor engine primitives as follows:66671. **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.682. **Output Types**: Steps use the following `output_type` assignments:69 - `specify`/`init` → `draft` (CDR/ChDR drafts stay in `.adlc/drafts/`, not published to comment bus)70 - `clarify`⭐ → `decision` (accepted/rejected CDR/ChDR list published to comment bus on the directives PR)71 - `publish` → `artifact-ref` (PR URL reference published, content stays on disk)72 - `prune`/`verify` → `findings` (redundancy/deprecation report published to comment bus)733. **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).744. **Supervision Default**: `hybrid`. Human gates are hard-enforced at `clarify`⭐ (approval of CDR/ChDR entries) and at final PR creation.755. **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`.