Harness Learnings

Principle

Agent sessions are ephemeral. Codebase knowledge is not. When an agent discovers a pattern through trial and error (failed tests, correction loops, review findings), that knowledge should persist so the next session starts smarter.

Operations

This skill has two modes: capture (write a learning) and consult (read learnings relevant to the current task).

How This Skill Is Invoked

Capture is auto-prompted by the lifecycle agents at trigger moments where the agent has likely done something that future sessions should know about. The auto-prompt sites are:

• devsquad.implement.execute after self-correction loops (2+ correction attempts, reverts of own work, max-attempt exhaustion)
• devsquad.implement.verify after discovering a test or build prerequisite through a failed run
• devsquad.review.code after producing Major or Critical findings that match a codebase-specific pattern
• devsquad.implement.finalize after human PR feedback contradicts prior agent output, or CI fails on a missing prerequisite

At each trigger, the calling agent surfaces a [Y] / [N] / [E] prompt before returning its output. Default is [Y] to capture. The user can also invoke this skill explicitly at any time ("add this as a learning", "capture this as a learning"); the skill runs in capture mode without a trigger.

Consult is automatic at the start of implement.execute, implement.verify, and review.code (see "When to Consult" below).

1. Capture: Record a Learning

When to Capture

When NOT to Capture

• Generic best practices already covered by coding-guidelines.md or .instructions.md
• One-time errors caused by typos, environment issues, or transient failures
• Learnings about the framework itself (report as issues instead)
• Context that only applies to a single task and will not recur
• Observations with no actionable guidance ("this was hard" is not a learning)

Capture Procedure

1. Read .memory/harness-learnings.md (create from template if it does not exist)
2. Deduplicate: scan existing entries for overlap
   • Match criteria: overlapping Scope (shared file paths or modules) AND similar failure type
   • If match found: increment Occurrences, update Last seen, upgrade Confidence if warranted
   • If no match: append new entry with next sequential L-NNN ID
3. Assign fields for new entries:
   • Phase: the lifecycle phase where this learning is most relevant for consumption (not necessarily where it was captured). A review finding about missing error handling should have Phase = implement if the fix belongs at coding time.
   • Dimension: what it regulates (maintainability, architecture, behaviour)
   • Scope: concrete file paths, directories, or module names. Use glob patterns when appropriate (e.g., src/api/**, *.controller.ts). This is the primary field agents use to match learnings to their current task.
   • Pattern: factual description of what happened (the observation)
   • Guidance: actionable instruction for what to do differently (the prescription). Must include file paths, commands, or specific checks.

…