Lessons Learned Skill

The lessons-learned skill is the CAPTURE step — the final step of the Archgate development workflow. It reviews what happened during a coding session and turns durable patterns into governance: new or extended Architecture Decision Records (ADRs), or entries in the project’s AI instruction file. This is how Archgate’s governance loop closes — every session can make the next one better.

What It Does

The skill captures learnings so they carry forward across all future sessions and agents. Concretely, it:

• Captures session learnings — patterns, mistakes, workarounds, and improvements discovered while coding
• Standardizes decisions — turns recurring patterns into documented ADRs so they are enforced consistently
• Extends existing ADRs — adds new Do’s/Don’ts, examples, or clarifications
• Creates new ADRs — when a learning covers a distinct topic no existing ADR scopes
• Updates project memory — records operational knowledge in the project’s AI instruction file

It never edits ADRs directly

The lessons-learned skill does not write ADR files itself. For both new ADRs and edits it delegates to the adr-author skill, which is the only authoring layer permitted to touch ADR files.

How It Works

1. Gather session context. Long sessions get compacted, so earlier errors and decisions may be lost. The skill reads the full session transcript from disk via archgate session-context claude-code. Because it runs as a sub-agent with its own session, it uses --skip 1 to read the parent session that holds the actual development work. If no transcript is available, it falls back to asking you targeted questions about the most time-consuming issue, mistakes an ADR could have prevented, and patterns worth standardizing.

2. Review the governance landscape. It runs archgate review-context --run-checks to see which domains were affected, the applicable ADR briefings, and the current automated check results — replacing several manual calls with one.

3. Classify each learning into a category that maps to a target (see below).

4. Decide: extend, create, or skip. It prefers extending an existing ADR when the learning adds a Do/Don’t, example, or clarification; creates a new ADR only for a distinct topic, an ADR that would otherwise bloat past ~200 lines, or a pattern seen in 3+ places; updates project memory for operational tips; and takes no action for trivia already covered.

5. Write the learnings — by delegating ADR work to adr-author, or by editing the project’s AI instruction file for operational knowledge.

6. Generate a summary report of everything captured.

Classification

Every learning is sorted into one category, which determines where it is recorded:

Category	Target	When to use
Architecture Pattern	ADR (architecture)	Module structure, dependency boundaries, naming, file organization
Backend Pattern	ADR (backend)	API design, middleware, validation, service patterns
Frontend Pattern	ADR (frontend)	Component patterns, state management, UI conventions
Data Pattern	ADR (data)	Schema design, migrations, data access patterns
General Convention	ADR (general)	Cross-cutting concerns: testing, error handling, formatting, dependencies
Custom Domain Pattern	ADR (custom domain)	Learnings that fit no built-in category — confirmed with you before registering a new domain
Operational Knowledge	Project AI instruction file	Quick tips, environment quirks, troubleshooting, API paths

The AI instruction file differs by editor — CLAUDE.md for Claude Code, .cursor/rules/*.mdc or .cursorrules for Cursor, .github/copilot-instructions.md for VS Code / Copilot, agents.md for OpenCode.

Output Format

The skill produces a structured report covering what it captured and what it deliberately skipped:

## Lessons Learned Report

### Session Summary
<Brief description of the task completed>

### Learnings Captured
**New ADRs Created:**
- <ADR-ID> <Title> (domain: <domain>) — <one-line description>

**Existing ADRs Updated:**
- <ADR-ID> <Title> — Added: <what was added>

**Project Memory Updated:**
- <instruction file> — Added: <what was added>

### No Action Needed
- <Learnings already documented or not worth capturing>

If nothing is worth capturing, it says so plainly rather than forcing documentation for trivial changes. A good learning is actionable, repeatable, specific, and non-obvious — “command files must not contain business logic” qualifies; “write clean code” does not.

How It Fits the Workflow

UNDERSTAND → PLAN → WRITE → VALIDATE → CAPTURE
                            (reviewer) (lessons-learned)

The developer agent invokes lessons-learned after archgate check and the reviewer skill confirm compliance, on initial task completion. It is skipped for minor follow-up tweaks. The skill is intentionally conservative: it proposes ADRs only for clear, repeated patterns backed by concrete code evidence, prefers extending existing ADRs over creating overlapping ones, and flags — rather than silently changes — anything that contradicts an existing ADR.

adr-author skill The authoring layer lessons-learned delegates to for every ADR change.

Note

For the exact syntax of archgate session-context, archgate review-context, and archgate check, see the authoritative reference at cli.archgate.dev.