agent-learn

Files (1)

• SKILL.md

SKILL.md (first lines)

# Learn Agent

The Learn agent runs as part of the AIDLC Validate+Learn phase after a feature passes validation, or as part of Close+Learn after an incident is resolved. Its job is to ensure that everything discovered during the cycle is captured in durable, agent-readable form so future work starts with full context.

## When to Invoke

- After a Feature passes Validate (development lifecycle)
- After an Incident passes Close (operational lifecycle)
- After any significant architectural decision that needs an ADR

## Responsibilities

### 1. Update PROJECT.md (Required)

The project memory file (`PROJECT.md` at repo root) is the quick-reference context document that all agents read at the start of a session. After every feature completion, the Learn agent must update it:

- **Add the feature** to the "Implemented Features" section with:
  - Feature number and title (linked to the GitHub issue)
  - Current status
  - A 2–3 sentence description of what was built and why
  - Sub-issues completed (linked to their GitHub issues)
  - Key technical decisions made during implementation
- **Update "Last updated" date** in the header
- **Update the Architecture Overview** if the feature changed the deployment stack, added services, or modified the directory structure
- **Update Conventions** if the feature established new patterns or changed existing ones

### 2. Write or Update ADRs (If Applicable)

If the feature involved significant architectural decisions — new services, technology choices, protocol decisions, schema changes — write an ADR capturing:

- The context and problem
- Options considered
- The decision and rationale
- Consequences and trade-offs

ADRs go in repo-root **`adr/`**, named `NNNN-title-with-dashes.md`. Copy from the bundled template [`spec-management/templates/adr-template.md`](../../spec-management/templates/adr-template.md) and read [`adr-guidance.md`](../../spec-management/templates/adr-guidance.md) for naming and when to write one.

### 3. Retrospective Notes on Tech Specs (If Applicable)

For each Tech Spec (Unit) in the feature, add a brief retrospective note at the bottom capturing:

- What differed from the plan and why
- Anything that was harder or easier than expected
- Patterns discovered that should inform future specs

### 4. Update Repo Documentation (If Applicable)

If the feature changed how things work in ways that affect onboarding or day-to-day development:

- Update `README.md` if top-level structure or quickstart changed
- Update `docs/` files if specific documentation areas are affected
- Update `AGENTS.md` if agent/skill discoverability changed

### 5. Note Process Friction (If Applicable)

If the AIDLC process itself had friction during this cycle, note it in a brief section at the bottom of the feature's retrospective. This feeds back into AIDLC process improvement.

## Output Format

The Learn agent produces a single commit (or PR) containing all documentation updates. The commit message follows the convention:

```
docs(learn): capture learnings from Feature #<N> — <title>
```

## Quality Criteria

- PROJECT.md accurately reflects the current state of the project after the feature
- A new agent starting a session and reading only PROJECT.md would have enough context to understand what exists, where it runs, and what decisions were made
- No stale information remains from before the feature was implemented
- ADRs, if written, are self-contained and don't require reading the full PR history to understand

From nathan-oakes/AI-DLC, MIT.