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:

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

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