capture-project-learning

name	capture-project-learning
description	Turn a HardwareVisualizer maintainer correction, repeated failure, surprising invariant, or costly investigation into an evidence-backed learning record and the right durable guardrail. Use when asked to record learnings, prevent the same AI mistake, update AGENTS/rules/hooks/skills, or when completed work reveals a reusable repository-specific lesson.

Capture Project Learning

Goal

Convert experience into a small durable improvement without turning chat history into always-on context.

The lifecycle is:

observe -> verify -> record -> promote -> enforce -> revalidate

Workflow

1. Decide Whether It Is A Learning

Record one when at least one is true:

• the maintainer corrected an assumption or product interpretation;
• the same CI, review, environment, or implementation failure repeated;
• investigation found a non-obvious invariant or evidence path;
• an undocumented design decision materially changed implementation;
• a manual check can become a deterministic regression guard.

Do not record a guess, secret, credential, personal absolute path, temporary check state, or generic software-engineering advice.

2. Search Before Adding

Search docs/agents/lessons/, docs/design-principles.md, CONTEXT.md, ADRs, architecture docs, scoped instructions, skills, tests, and CI. Update or supersede an existing lesson instead of creating a duplicate.

3. Verify The Cause

Confirm the observation against current evidence. Prefer current code/tests, leaf-job logs, runtime/SQLite data, rendered artifacts, release assets, and current GitHub state. If the cause is not confirmed, record a candidate and do not promote it as a rule.

Separate the durable invariant from time-specific evidence such as a dependency version, PR number, runner timing, or spec revision.

4. Add One Learning Record

Create one file under docs/agents/lessons/ using the required frontmatter in that directory's README. Use an ID of the form LRN-YYYYMMDD-short-slug, update the records index, and state exactly when the lesson must be revalidated.

5. Promote To The Real Owner

Use this routing:

• vocabulary -> CONTEXT.md;
• cross-cutting decision lens -> docs/design-principles.md;
• specific trade-off -> ADR;
• current ownership/structure -> architecture doc or owner README;
• always-on AI constraint -> root or scoped AGENTS.md;
• path-specific AI constraint -> .agents/rules/**;
• repeated multi-step procedure -> .agents/skills/**;
• deterministic invariant -> test, non-mutating script, hook, or CI;
• expiring/environment fact -> learning record only.

Keep hooks cheap and deterministic. They may validate paths, schemas, links, generated-file edit attempts, or exact dependency invariants. They must not infer product meaning, clean-room contamination, or change kind.

6. Validate

Run:

npm run check:agent-guidance
git diff --check

Run any new focused regression test or script. Inspect the diff for duplicated or conflicting guidance.

Completion Criteria

A learning is complete when:

• its cause is labeled confirmed or candidate honestly;
• its durable rule has one canonical owner;
• AI entry points link to, rather than duplicate, detailed facts;
• deterministic behavior is enforced by a test/script/CI where practical;
• the record says when it can expire or must be revalidated.