Imported from yesplease-studio/prd-please (skills/prd-learner/SKILL.md). Install upstream with npx skills add yesplease-studio/prd-please --skill prd-learner. Copyright stays with the author.

Skill: prd-learner

Purpose: Capture implementation learnings and codify them back into the Strategic PRD so that future agents, sessions, and team members inherit the knowledge. This skill closes the feedback loop — every mistake becomes a permanent rule.

When to Use

• After a validation failure (something was built wrong and the root cause is worth capturing).
• After resolving a non-trivial bug or issue during implementation.
• After a session where repeated mistakes occurred.
• When a human explicitly asks to "capture learnings", "update the PRD based on what happened", or similar.
• Periodically, at the end of a development sprint or cycle, as a retrospective step.

Core Principle

Learnings must be actionable, specific, and permanent. "We should be more careful" is not a learning. "All public API endpoints must implement rate limiting (added after brute-force incident on /auth/login)" is a learning.

A good learning results in a concrete change to the Strategic PRD: a new guardrail, a tightened requirement, an added acceptance criterion, a new "don't." The learning entry in Section 8 provides the why; the amendment in Sections 5-6 provides the what.

Workflow

Step 1: Gather Context

Collect information about what happened. Sources, in order of preference:

1. Validation report from prd-validator — if the learning was triggered by a validation failure, start here. The report identifies which requirements were unmet and why. In the build loop, this is <project_scope>/validation/<batch_id>-REPORT.md.

2. Impl agent reports — the notes_for_learner field from each implementation sub-agent's structured report. This is the designated pipe for patterns and workarounds observed during building; sub-agents record them there precisely so this skill can consume them.

3. Workaround signatures — the Workaround signatures table in LOOP-STATE.md, if the project runs the build loop. Recurring signatures are the strongest signal this skill receives (see Pattern Detection below).

4. Session transcript / conversation history — review the recent agent session for: errors encountered, workarounds applied, repeated attempts, corrections, and patterns.

5. Human input — if automated sources are insufficient, ask the human via AskUserQuestion:

   • "What was the most surprising or time-consuming issue in this session?"
   • "Were there mistakes that a clearer requirement or guardrail could have prevented?"
   • "Did you discover any patterns that should be standardized?"

Step 2: Load Current PRD State

Read the full Strategic PRD to understand:

• Existing requirements (Section 5) — to check if the learning is already covered.
• Existing guardrails (Section 6) — to check for gaps.
• Existing learnings (Section 8) — to avoid duplicates and to see patterns.
• Dependencies (frontmatter depends_on) — the learning might apply to a dependent PRD instead.

Step 3: Classify Each Learning

For each distinct learning identified, classify it:

Step 4: Draft Amendments

For each learning that requires a PRD change, draft:

1. The learning entry (for Section 8):

### L-XXX: [Short descriptive title]
- **Date:** YYYY-MM-DD
- **Domain:** [domain]
- **Related requirements:** [requirement IDs, or "new" if adding]
- **What happened:** [Factual description of the incident or discovery]
- **Root cause:** [Why it happened — what was missing or wrong in the PRD]
- **Amendment made:** [Precise description of what changed in the PRD]
- **Status:** resolved

2. The inline amendment (in Sections 5 or 6):

• For a new guardrail: the exact DO or DON'T text to add to Section 6.
• For a tightened requirement: the specific change to the requirement row in Section 5.
• For a new requirement: the complete requirement row to add.
• For amended acceptance criteria: the specific criteria to add or modify.

Every inline amendment should include a reference to its learning ID so that future readers can trace the rule back to the incident. Format: add [L-XXX] at the end of the amended text.

Step 5: Present for Approval

Show the human the proposed changes:

## Learning Report — PRD-001

### Session Summary
[Brief description of what was being built and what triggered the learning capture]

### Proposed Amendments

**1. New guardrail (Section 6):**
- DON'T expose stack traces or internal error details in API responses. Return generic error messages with correlation IDs for debugging. [L-003]

**2. Tightened requirement (Section 5.2, TECH-01):**
- Added acceptance criterion: "Rate limiting applied: max 10 requests per minute per IP on authentication endpoints." [L-003]

**3. New requirement (Section 5.2):**
| ID | Severity | Requirement | Acceptance Criteria | Phase |
|----|----------|-------------|-------------------|-------|
| TECH-08 | must | All public endpoints implement rate limiting | Configurable per-endpoint; default 60 req/min; returns 429 with Retry-After header | R1 |
[L-003]

### Watchlist (below threshold — tracking)
- Supabase client timeout on cold start: seen once this sprint. Not proposing yet; will promote if it recurs.

### No Action Needed
- Agent timeout during build was environmental (CI runner resource limits), not a PRD gap.

### Patterns Observed
- This is the second learning related to API security (see also L-001). Consider whether a dedicated security review step should be added to the build workflow.

Threshold discipline: below-threshold signals (seen once, plausibly one-off) go to the Watchlist, never to Proposals. The Proposals section is for things ready to commit to as permanent rules. A learning report with empty Proposals and a populated Watchlist is a valid outcome — do not invent amendments to justify the run.

Wait for human approval before any changes are applied.

Step 6: Apply (via prd-author)

Once approved, invoke the prd-author skill in edit mode to apply the amendments. The prd-learner does not edit the PRD directly — prd-author is the single authoritative writing layer.

Provide prd-author with:

• The specific amendments to make (from Step 4).
• The learning entries to add to Section 8.
• The change summary format.

After prd-author applies the changes:

• Notify prd-taskmaster that affected task contexts may need regeneration.
• If the project has a CONTEXT-PACK.md, regenerate it via the prd-context-pack skill — amendments invalidate the pack.
• If the project runs the build loop, update LOOP-STATE.md via the prd-loop skill: decrement Learner debt and Apply debt, increment workaround signature counts for any signatures this run identified, and mark Generalizing ADR proposed? = yes on any signature whose ADR proposal was approved.

Quality Criteria for Learnings

Every learning must be:

• Actionable — It results in a concrete PRD change (or a clear reason why no change is needed).
• Specific — It names exact patterns, endpoints, behaviors, thresholds — not generalities.
• Non-obvious — It captures something that wasn't apparent from the original PRD. Obvious requirements that were simply missed belong in prd-author edit, not here.
• Repeatable — The issue could happen again if not addressed. One-off environmental issues are not learnings.

Good learning: "Authentication endpoints must implement rate limiting — brute-force attempt on /auth/login exposed the lack of throttling."

Bad learning: "We should write more secure code." (Not specific, not actionable, not tied to a PRD change.)

Patterns and Escalation

Pattern Detection

When adding a new learning, check Section 8 for related entries. If this is the third or more learning in the same domain or area, flag it as a pattern:

"This is the third learning related to API security (L-001, L-003, L-005). This pattern suggests the PRD may need a dedicated security requirements subsection or that security should be elevated as a cross-cutting concern."

Pattern detection helps the human decide whether a more fundamental PRD restructuring is needed, rather than just incremental patches.

Workaround Signatures → Generalizing ADRs

When the project runs the build loop, LOOP-STATE.md tracks workaround signatures — the shape of a workaround, recorded the second time it appears (the first looks like a one-off; the second is the signal). This skill is the consumer of that table:

• Count = 2: note the recurrence in the learning report's Watchlist. Not yet a proposal.
• Count >= 3: propose a generalizing ADR — a rule that would obviate the workaround class entirely. Include: the signature, occurrences across batches, the recommended scope of the rule, a one-paragraph sketch, and what future work it unblocks. Route the proposal through the standard approval path; once approved, it becomes an ADR via archgate adr create (or an import, if a registry pack covers it — see systems/prd/SYSTEM.md §8.2).

This is the runtime complement to prd-taskmaster's adr_candidate flag: taskmaster predicts which decisions need enforcement before building starts; signature tracking catches the ones that only reveal themselves during the build.

Escalation

Escalate to a human without proposing amendments when:

• The learning suggests the solution approach (Section 4) is fundamentally wrong.
• The learning reveals a conflict between two must requirements.
• The learning applies to a PRD the learner doesn't have access to.
• The pattern detection suggests systemic issues beyond individual amendments.

What This Skill Does NOT Do

• Does not edit the PRD directly. All changes go through prd-author.
• Does not write or modify code. It captures knowledge, not implementations.
• Does not validate. Validation is prd-validator's job. This skill runs after validation has already identified issues.
• Does not create new PRDs. If a learning suggests entirely new scope, it flags this for the human to decide.

Token Optimization

• Selective PRD loading. When triggered by a validation report, load only the sections referenced in the report (plus Section 8 for existing learnings). Only load the full PRD if the learning seems to span multiple domains.
• Batch learnings. When multiple issues arise in a single session, batch them into one learning report rather than running the skill multiple times. Each distinct learning gets its own L-XXX entry, but the human approval happens once for the whole batch.
• Concise proposals. The amendment drafts should be minimal — the exact text to add or change, not a lengthy analysis. The learning entry provides context; the amendment is the action.