implementation-memory skill

Implementation Memory

Overview

Implementation memory is a compact, fixed-size set of rules that improves future /build executions. It captures durable lessons from completed builds, code review feedback, test failures, and user feedback, then applies only the relevant lessons to later implementation work.

This is procedural memory, not history. It stores rules for how to implement better next time. It does not store product context, design history, changelog entries, ADRs, raw retrospectives, PR transcripts, or conversation logs.

This mechanism is harness-agnostic by design. It uses a plain markdown file in the repo (.bla/implementation-memory.md) intentionally. It is not tied to any agent's native memory system. Any AI agent that can read markdown and follow instructions can consume and update it.

This is an internal flow mechanism. Users do not invoke it as a slash command or choose it as a standalone workflow. Existing build commands and build-oriented assistant rules call it automatically at the defined points in the /build flow.

Capture Points

Implementation memory can be fed from multiple workflow stages — not only /build:

Source	When	What to extract
/wb (bar raiser gate)	After a PR/FAQ or 5CQ bounces on the same bar-raiser question across features	The recurring gap in customer evidence or problem framing, stated as a rule for future Working Backwards work
/design (design gate)	After a requirement bounces at the design gate 3 or more times	The recurring reason the requirement keeps failing the gate, stated as a rule for future design work
/spec (coherence review)	After a coherence-review finding recurs across specs	The cross-spec inconsistency pattern that coherence review keeps catching
/build (post-implementation review)	After PASSED WITH FIXES NEEDED or user validation	Procedural lessons from fix tasks, debug cycles, review findings
/review (code review)	After review feedback is resolved	Recurring review findings that apply beyond one PR
/learn (COE)	After corrective actions are defined	Operational lessons that should influence future implementation

All sources use the same Quality Memory Review process, admission checks, and rejection rules. Record in the rule's Phase field the phase whose work the rule constrains, so later selection scopes it correctly. For the first four sources that is the capturing phase itself — /wb → wb, /design → design, /spec → spec, /build → build — which is what makes every value the enum admits reachable: a value no source can write would be a filter hiding rules nobody can create. /review and /learn are capture points, not phases: a rule captured there inherits the Phase of the work it reviewed — a review finding about implementation is Phase: build, a COE action about operational practice is Phase: operate — because the Phase field names the phase whose work the rule governs, and there is no pre-execution selection at /review or /learn to scope. The enum is therefore unchanged: no review or learn value exists. Reachability on the write side is not enough on its own — a value every source can write but no command ever selects would hide rules just as effectively, from the read side, so Pre-Build Selection step 0 names which phases have a selection point and which are reserved, and a Phase value is only fully reachable once both sides hold.

Internal Flow Hooks

Use this mechanism in these places:

1. Before /build task execution: read the current spec/tasks first, then select active memory rules as defined in Pre-Build Selection below — a rule is selected if its Phase is build and ANY signal matches (Tags, File patterns, or Applies when). That section is the single definition of the selection semantics; this hook only says when it runs.
2. After implementation review (semi-automatic trigger): when the verdict is PASSED WITH FIXES NEEDED, the agent MUST automatically extract up to 2 candidate learnings from the fix findings and present them to the user for Accept / Reject / Edit. This is the primary memory population path. When the verdict is PASSED, prompt the user to test the delivered behavior and bring back failures or feedback.
3. After user validation or explicit request: run a Quality Memory Review using implementation results, implementation review, test/debug feedback, and user feedback to decide whether memory should be updated.
4. After /review findings are resolved: if the review surfaced recurring patterns (same finding across 2+ PRs or explicitly flagged as "this keeps happening"), extract candidates and present for Accept / Reject / Edit.
5. After /learn corrective actions: if a COE produces an implementation-level corrective action (not an org/process action), extract a candidate and present for Accept / Reject / Edit.
6. After a requirement bounces at the /design gate 3 or more times: extract a candidate with Phase: design describing why the requirement kept failing the gate, and present for Accept / Reject / Edit. Without this hook a requirement rejected three times leaves no trace.
7. After a coherence-review finding recurs across specs: when /spec produces the same coherence finding in 2 or more specs, extract a candidate with Phase: spec and present for Accept / Reject / Edit.
8. Periodic nudge: after 3 builds without a memory update (tracked via Builds without update counter at the bottom of the memory file), include in the end-of-build summary: "You have had N builds without memory update. Would you like a quick Quality Memory Review?"

Do not use this skill to replace requirements, design documents, ADRs, release notes, PR/FAQ, postmortems, or review artifacts.

Canonical Artifact

The project-level memory artifact is:

.bla/implementation-memory.md

If the file does not exist before a build, continue without memory guardrails. After the build, create it only when at least one candidate learning passes the admission bar. A repository may also keep an empty canonical file with the required structure so future builds have a stable location.

Memory Limits

The memory is intentionally small:

• Maximum 12 active rules.
• Maximum 120 words per active rule.
• Maximum 2 candidate learnings extracted per Quality Memory Review.
• Rewrite the whole file when updating; never append a chronological build log.
• Prefer rules that prevent bugs, review rework, security issues, rollout failures, weak tests, or operational gaps.

Active Rule Format

Every active rule must use this shape:

### IM-XXX: [Short rule name]
Tags: [api, error-handling, testing, infra, ui, data-pipeline, security, observability, workflow, ...]
Phase: [wb | design | spec | build | deploy | operate]
File patterns: [optional glob patterns, e.g. src/api/**, tests/integration/**]
Applies when: [Spec/component/risk conditions where this rule is relevant.]
Rule: [Actionable implementation behavior.]
Avoid: [Specific behavior to avoid.]
Evidence: [Review feedback | user feedback | test failure | build defect | repeated pattern.]
Impact: [Critical | High | Medium]
Confidence: [Proven (Prevented >= 1 backed by evidence) | Established (applied successfully) | New (just added)]
Hit count: [N — number of builds where this rule was selected and applied]
Prevented: [N — number of times this rule demonstrably prevented an issue; increment only with concrete evidence that the rule stopped something]
Created: [YYYY-MM-DD]
Last used: [YYYY-MM-DD]
Builds on: [[IM-YYY]] (optional — reference to a related/prerequisite rule)

Use stable IDs. When removing a rule, do not renumber unrelated rules unless the file is being deliberately compacted for readability.

Prevented is an evidence counter, not a confidence signal. Increment it only when something concrete stopped: a validator blocked, a test failed before merge, or a review cited the rule by ID. Applying a rule, or believing it helped, is not evidence. Confidence: Proven therefore requires Prevented >= 1 backed by such evidence; a rule whose only evidence is unattributed feedback stays at Established with Prevented: 0.

Pre-Build Selection

Before implementation starts:

1. Determine the current phase from the command in flight: /wb → wb, /design → design, /spec → spec, /build → build, /deploy → deploy, /operate → operate. This section runs at the start of every phase, not only /build. Three phases have a selection point wired into their command today: design (.claude/commands/design.md → Step 0e), spec (.claude/commands/spec.md → Read the existing context) and build (.claude/commands/build.md → step 2c). wb, deploy and operate are reserved: a rule stored under one of them is admitted normally, counts against the 12-rule cap, and will not fire until a selection point exists in that command — so accept such a rule only when it is worth a slot it cannot yet use.

2. Read the current .bla/specs/<slice-name>/requirements.md, design.md, tasks.md, and coherence-review.md if present.

3. Read .bla/implementation-memory.md if it exists.

4. Select active rules using this multi-signal matching. A rule is selected when its Phase matches the current phase determined in step 0 AND any one of the following signals matches:

   • Tags match: rule tags overlap with the current spec's domain/technology areas.
   • File patterns match: the spec's tasks touch files matching the rule's glob patterns.
   • Applies when matches: the LLM judges the prose description to be relevant to the current spec, task, component, dependency, or risk profile.

   The three signals above remain an OR among themselves — one is enough. Phase is an additional filter layered on top, not a replacement: a rule whose Phase does not match the current phase is never selected, however strongly its tags, file patterns, or prose match. A rule with no Phase line is treated as build.

5. Convert selected rules into implementation guardrails, test checks, or review checks.

6. Ignore unmatched rules. They are not requirements for the current build.

7. Increment Hit count for each selected rule.

Phase scoping changes which rules are selected, never how many may exist: the cap defined in Memory Limits above is unchanged at 12 active rules in total, not 12 per phase.

Memory rules never override approved requirements, design, tasks, or coherence-review action items.

Semi-Automatic Trigger (Primary Population Path)

When the implementation review verdict is PASSED WITH FIXES NEEDED, the agent does not wait for the user to request memory update. Instead:

1. Generate a structured self-reflection (2-3 sentences): "What went wrong? Why? What would have prevented it?"
2. Use the self-reflection (not the raw findings) to extract up to 2 candidate learnings.
3. Present candidates to the user in this format:

Memory candidates extracted from this build:

[1] IM-00X: [Short rule name]
    Tags: [...]
    Applies when: [...]
    Rule: [...]
    Avoid: [...]

[2] IM-00Y: [Short rule name]
    Tags: [...]
    Applies when: [...]
    Rule: [...]
    Avoid: [...]

Actions: [Accept all] [Accept 1 only] [Accept 2 only] [Edit before saving] [Reject all]

1. Apply the user's decision. If accepted, run admission checks and write.
2. If rejected, do not ask again for this build.

This ensures memory is populated even when users forget to ask for Quality Memory Review.

Post-Review User Validation Handoff

After implementation review is written (for PASSED verdicts without fix tasks), do not treat the model review as the final validation of product behavior. The final build response must explicitly hand the implementation to the user for real testing and invite a debug loop.

Use this shape:

Implementation is complete and implementation review has run. Please test the delivered behavior in the product. If anything is wrong, bring me the failure, error, or feedback and we will debug it together until it is OK. After you consider the implementation validated, ask me to run Quality Memory Review and I will capture only durable learnings worth keeping.

If no user validation/debug feedback is available yet, skip memory update and report: Implementation memory skipped: waiting for user validation/debug feedback and an explicit Quality Memory Review request.

Quality Memory Review

Run this after the user asks for it, confirms the implementation is validated, or when the semi-automatic trigger fires. Use implementation verification, implementation-review findings, user test results, debug fixes, and final user feedback as evidence:

1. Self-reflection first — Before extracting candidates, generate a 2-3 sentence structured reflection: "What went wrong or almost went wrong? Why did it happen? What general rule would have prevented it?" This reflection is the input for extraction, not the raw findings.
2. Extract at most 2 candidate learnings from the reflection.
3. Reject any candidate that fails the rejection rules.
4. Add or merge only candidates that pass at least 2 admission checks.
5. Merge duplicates into existing active rules instead of adding near-copies.
6. If the memory would exceed 12 active rules, prune weaker rules before writing.
7. Rewrite the whole memory file if an update is warranted.
8. Leave memory unchanged when no candidate meets the bar.
9. Reset the Builds without update counter to 0 when memory is updated.

The Quality Memory Review response must state whether implementation memory was updated, unchanged, or skipped. When it changes:

• Summarize the rule IDs added, merged, or removed.
• Show the diff (what was added/changed/removed) directly in the response so the user sees changes without opening the file.

When it is skipped, state why.

Admission Checks

A candidate learning must pass at least 2 of these checks:

• Avoids a likely future bug.
• Avoids repeated review rework.
• Improves tests, security, operations, or rollout safety.
• Applies beyond one feature.
• Corrects a recurring agent tendency.

A defect that recurs even though a memory rule already covers it means memory is the wrong remedy: promote it to a declared project pattern or a mechanism via skills/mechanism-creation/SKILL.md, and do not add a second memory rule for the same defect.

Rejection Rules

Reject candidates that are:

• Product requirements.
• Feature-specific facts.
• Architecture decisions or ADR content.
• Release notes or changelog entries.
• Raw retrospectives, raw review transcripts, or raw user quotes.
• Secrets, credentials, customer data, private incident details, or proprietary feedback.
• Environment-specific operational facts that will become stale.
• Stylistic preferences without quality impact.

Staleness and Decay

Rules decay over time. The following thresholds guide pruning:

• Stale threshold: a rule not selected (Last used not updated) for >90 days is a candidate for pruning.
• Inactive threshold: a rule not selected in 5 consecutive Quality Memory Reviews is a candidate for pruning.
• Low-confidence, low-hit: a rule with Confidence: New and Hit count: 0 after 3 builds is a candidate for pruning.

Staleness alone does not trigger automatic removal. The agent flags stale rules during Quality Memory Review and asks the user: "Rule IM-XXX has not been used in N days. Keep or remove?"

Merge, Conflict, and Pruning Rules

When a candidate overlaps an existing rule, merge it into the existing rule and update Evidence, Impact, Confidence, Hit count, or Last used if warranted.

When rules conflict, keep the more specific and higher-impact rule. If the conflict is ambiguous, leave memory unchanged and report the conflict in the final response.

When pruning is required, remove in this order:

1. Rules that exceed the stale threshold (>90 days unused).
2. Rules that are too specific to one feature.
3. Rules duplicated by requirements, design, ADRs, or repository docs.
4. Rules with Confidence: New and Hit count: 0.
5. Low-impact or mostly stylistic rules.
6. Rules superseded by a stronger rule.

Rule Composition

Rules may reference other rules using the Builds on: [[IM-YYY]] field. This indicates:

• The referenced rule should also be selected when the referencing rule is selected.
• Together they form a composite pattern that captures a more complex lesson without exceeding the 120-word limit per rule.
• When pruning, if a rule that others build on is removed, check whether dependent rules still make sense alone.

Domain-Scoped Memory (for large projects)

For projects with distinct domains (e.g., monorepos), the memory may be split:

.bla/implementation-memory.md              # global (max 12 rules)
.bla/implementation-memory-<domain>.md     # domain-scoped (max 6 rules each)

Pre-build selection loads the global file plus the domain file matching the current spec's primary domain. Domain files follow the same format and rules but with a reduced cap of 6 rules.

When to split: only when the global memory is consistently full (12 rules) AND rules from different domains are competing for slots. Do not split preemptively.

Manual Scenarios

Scenario	Expected behavior
No memory file exists	Build proceeds; Quality Memory Review may create memory if strong candidates exist.
Memory has 12 rules and 2 strong candidates	Merge or remove weaker rules; final memory still has at most 12 rules.
Candidate is a product requirement	Reject candidate.
Candidate duplicates an existing rule	Merge/refine existing rule instead of duplicating.
Current spec matches no active rules	Select no memory guardrails.
Review/user feedback is unavailable (PASSED verdict)	Skip memory update and ask the user to test/debug before requesting Quality Memory Review.
PASSED WITH FIXES NEEDED verdict	Semi-automatic trigger fires: extract candidates, present to user for Accept/Reject/Edit.
User validates after debug and asks for Quality Memory Review	Extract up to 2 durable learnings from the full implementation/review/test/debug cycle.
3 builds without memory update	Nudge in end-of-build summary.
Rule IM-003 not used in 90+ days	Flag during next Quality Memory Review; ask user to keep or remove.
/review finds recurring pattern	Extract candidate and present for Accept/Reject/Edit.
/learn COE has implementation-level action	Extract candidate and present for Accept/Reject/Edit.