learn

name	learn
description	Distill learnings from completed features and propose amendments to constitution.md or prompt.md. Use after feature completion. Triggers on: capture learnings, learn from feature, distill learnings, relentless learn.

Relentless Learning System

Capture learnings from completed features and propose amendments to improve future runs.

Philosophy: "Loop Ralph" - Create a feedback loop where each feature execution improves the system for future features.

---

SpecKit Workflow

This skill is optional and runs after feature completion:

specify → plan → tasks → convert → analyze → implement → (optional) learn

Prerequisites:

• Feature must be complete (all stories passes: true or skipped: true)
• progress.txt must exist with iteration learnings
• prd.json must exist with execution data
• constitution.md and/or prompt.md must exist in relentless/

---

The Job

1. Extract learnings from completed feature (using CLI scripts)
2. Classify each learning (Constitutional / Tactical / Discard)
3. Generate proposals for human approval
4. Apply approved amendments to constitution.md or prompt.md
5. Save learning log to feature directory
6. Update aggregate stats

---

Step 0: Run Extraction Scripts

IMPORTANT: Use CLI scripts for extraction - do NOT read entire files into context.

Run the extraction scripts from .claude/skills/learn/scripts/:

# Main extraction - runs all extractors
bash .claude/skills/learn/scripts/extract-learnings.sh relentless/features/<feature-name>

# Individual extractors (run by main script):
# - extract-patterns.sh - Patterns from progress.txt
# - extract-costs.sh - Cost accuracy from prd.json
# - extract-failures.sh - Failed checks from checklist.md
# - extract-errors.sh - Error patterns from progress.txt

The output is compact JSON (~500 tokens max):

{
  "patterns": ["Pattern 1: description", "Pattern 2: description"],
  "costs": {"feature": "name", "estimated": 0.45, "actual": 0.52},
  "failures": ["Unchecked item 1", "Unchecked item 2"],
  "errors": ["Error context 1", "Error context 2"]
}

If more context is needed for a specific story:

# Extract session context for deeper investigation
bash .claude/skills/learn/scripts/extract-session-context.sh relentless/features/<feature-name> US-XXX

---

Step 1: Parse Extracted Data

Parse the JSON output from the extraction scripts:

1. Patterns: Reusable learnings discovered during implementation
2. Costs: Cost accuracy metrics (estimated vs actual)
3. Failures: Unchecked checklist items (potential gaps)
4. Errors: Error patterns that were fixed (potential rules)

Count and categorize:

• How many patterns were discovered?
• Was cost estimation accurate (>80%)?
• Are there unchecked checklist items (quality gaps)?
• What error patterns emerged?

---

Step 2: Classify Learnings

For each learning, classify as:

Type	Target	Criteria	Example
Constitutional	constitution.md	Applies to ALL features, governance/quality/process, prevents significant issues	"Always export new types with implementation"
Tactical	prompt.md	Specific to task types or tech stack, workflow tips, common pitfalls	"Mock CLI calls in adapter tests"
Discard	None	One-time edge case, already covered, too specific	"Fixed typo in variable name"

Constitutional criteria (becomes a MUST or SHOULD rule):

• Applies universally to all features
• Related to governance, quality, or process
• Prevents significant issues if violated
• Not already covered in constitution

Tactical criteria (becomes a prompt.md pattern):

• Specific to certain task types or tech stack
• Workflow tip or common pitfall
• Helps agents avoid repeated mistakes
• Not governance-level

Discard criteria (do not propose):

• One-time edge case
• Already covered by existing rules
• Too specific to be reusable
• Subjective preference

---

Step 3: Generate Proposals

Generate maximum 5 constitutional + 5 tactical proposals per feature.

Constitutional Proposal Format:

### PROP-C01: [Short Title]

**Target:** constitution.md > Principle [N] > [MUST|SHOULD]

**Amendment:**
> [1-2 sentence rule in imperative form]

**Evidence:**
> [Quote from progress.txt showing the issue]

**Classification:** Constitutional - [Rationale why this applies to all features]

Tactical Proposal Format:

### PROP-T01: [Short Title]

**Target:** prompt.md > [Section Name]

**Amendment:**
> [1-2 sentence tip or pattern]

**Evidence:**
> [Quote from progress.txt showing the context]

**Classification:** Tactical - [Rationale why this is task-specific]

Discarded Learnings (include for transparency):

### Discarded Learnings

| Learning | Reason |
|----------|--------|
| Fixed typo in variable name | One-time edge case |
| Used specific API endpoint | Already covered in docs |

---

Step 4: Present for Human Approval

Use the proposal template from templates/learning-proposal.md to format the output.

The proposal should include:

1. Feature Summary: Name, stories, escalations, cost accuracy
2. Constitutional Proposals: PROP-C01, PROP-C02, etc.
3. Tactical Proposals: PROP-T01, PROP-T02, etc.
4. Discarded Learnings: With reasons
5. Approval Request: Ask user to approve, modify, or reject each proposal

Ask the user:

Please review the proposals above. For each one:
- APPROVE: Apply as written
- MODIFY: Suggest changes
- REJECT: Do not apply

Which proposals do you approve?

---

Step 5: Apply Approved Amendments

For each approved proposal:

Constitutional Amendments (constitution.md):

1. Read current version from constitution.md frontmatter
2. Find the appropriate Principle section
3. Add the new rule under MUST or SHOULD
4. Update version number:
   • MUST rules: Bump MINOR version (e.g., 2.0.0 → 2.1.0)
   • SHOULD rules: Bump PATCH version (e.g., 2.0.0 → 2.0.1)
5. Update LAST_AMENDED_DATE to today
6. Add amendment note at top of file

Amendment note format:

<!-- Amendment: v2.1.0 - Added [rule title] from feature [feature-name] -->

Tactical Amendments (prompt.md):

1. Find the appropriate section in prompt.md
2. Add the new pattern or tip
3. Update "Generated" date at bottom
4. If no appropriate section exists, create a new "## Learned Patterns" section

---

Step 6: Save Learning Log

Create a learning log file in the feature directory:

Path: relentless/features/<feature-name>/learnings.md

# Learnings: [Feature Name]

**Extracted:** [date]
**Proposals Generated:** [count]
**Approved:** [count]
**Applied:** [count]

## Constitutional Amendments Applied

- PROP-C01: [Title] → constitution.md v[version]

## Tactical Amendments Applied

- PROP-T01: [Title] → prompt.md

## Discarded Learnings

- [Learning] - [Reason]

---

*Generated by /relentless.learn*

---

Step 7: Update Aggregate Stats

Run the stats generator to update relentless/stats.md:

bash .claude/skills/learn/scripts/generate-stats.sh relentless

This generates a human-readable report with:

• Total features, stories, completion rate
• Cost summary (estimated vs actual)
• Token usage
• Complexity distribution
• Escalation rate
• Model usage breakdown

The stats file is for human review, NOT loaded into agent context.

---

Version Bumping Rules

Amendment Type	Version Bump	Example
MUST rule	MINOR	2.0.0 → 2.1.0
SHOULD rule	PATCH	2.0.0 → 2.0.1
Multiple rules	Highest bump applies	2.0.0 → 2.1.0 if any MUST

Never bump MAJOR - only /relentless.constitution can do that (for breaking governance changes).

---

Common Patterns to Look For

Constitutional-Level Patterns:

• Type safety rules (export types with implementation)
• Testing patterns (TDD workflow, test structure)
• Error handling patterns (graceful degradation)
• Documentation requirements (JSDoc, README updates)
• Code quality patterns (zero-lint, typecheck)

Tactical-Level Patterns:

• Schema naming conventions (XxxSchema for Zod)
• Mock patterns for testing (mock CLI, mock adapters)
• File organization patterns (where to put new files)
• Common pitfalls for specific tech stack
• Performance optimizations

Patterns to Discard:

• Typo fixes
• One-time debugging steps
• Temporary workarounds (already removed)
• Personal preferences (formatting choices)
• Already documented patterns

---

Example Session

Input:

/relentless.learn 001-queued-prompts

Extraction Output:

{
  "patterns": [
    "Atomic writes: Use temp file + rename for safety",
    "Zod naming: Use XxxSchema to avoid no-redeclare"
  ],
  "costs": {"estimated": 0.45, "actual": 0.52, "accuracy": "87%"},
  "failures": [],
  "errors": ["ESLint no-redeclare on UserStory type - fixed with XxxSchema pattern"]
}

Generated Proposals:

### PROP-C01: Atomic Write Pattern

**Target:** constitution.md > Principle 11 (Data Safety) > SHOULD
**Amendment:**
> Use atomic writes (temp file + rename) when modifying files to prevent corruption.

**Evidence:**
> "Uses atomic writes (temp file + rename) to prevent corruption" - progress.txt

**Classification:** Constitutional - Applies to all file-modifying operations across features

User Response: "APPROVE PROP-C01"

Applied: constitution.md v2.0.1 updated with new SHOULD rule

---

Notes

• This skill is opt-in - only run after user decides to capture learnings
• Maximum 10 proposals per feature to avoid overwhelming the user
• Use extraction scripts to minimize context usage
• Human approval required for all amendments
• Stats file is for transparency, not agent context
• Session context extraction is available for deeper investigation when needed