Memory Alignment Check

---
name: memory-alignment-check
description: After QA PASS, compare the Story's implementation footprint against relevant memory entries. Reports confirmed entries, contradictions, and new knowledge candidates. Never writes to memory — produces a delta report for Discovery to action.
license: ELv2
compatibility: Works with any filesystem-based AI coding agent
metadata:
  author: gaai-framework
  version: "1.0"
  category: cross
  track: cross-cutting
  id: SKILL-MEMORY-ALIGNMENT-CHECK-001
  updated_at: 2026-02-26
  status: stable
inputs:
  - contexts/artefacts/impl-reports/{id}.impl-report.md
  - contexts/artefacts/stories/{id}.story.md
  - contexts/memory/index.md
  - [selective memory entries by scope tags]
outputs:
  - contexts/artefacts/memory-deltas/{id}.memory-delta.md
---

# Memory Alignment Check

## Purpose / When to Activate

Activate after QA verdict is PASS — never before (avoids analysis on code that will change).

This skill checks that long-term memory (decisions, patterns, project context) remains accurate after a Story is delivered. It compares only the Story's implementation footprint against relevant memory entries — not the full codebase.

The codebase is the source of truth for implementation.
Memory is the source of truth for decisions and patterns.
This skill checks that both remain consistent after each delivery.

**This skill reports. It never writes to memory.**

---

## Process

### 1. Extract Implementation Footprint

From `{id}.impl-report.md`:
- Files modified or created
- New modules or services introduced
- Patterns applied during implementation
- Technical decisions made during implementation
- New integrations or external dependencies introduced

### 2. Retrieve Relevant Memory (Selective)

Using `contexts/memory/index.md`:
- Identify memory entries whose tags intersect the Story's scope and touched modules
- Load only those entries — do not load all memory
- Scope: project context, patterns, decisions relevant to the implementation footprint

### 3. Compare Footprint Against Memory

For each relevant memory entry, assign one verdict:

- **CONFIRMED** — implementation is consistent with what memory states
  → Record entry ID, suggest `last_verified_at` update to today, `verified_against_story` to Story ID

- **CONTRADICTED** — implementation contradicts or obsoletes what memory states
  → Record exact contradiction, affected memory entry ID, severity (high / medium / low)

- **UNADDRESSED** — memory entry is not touched by this Story
  → Skip — no verdict needed

### 4. Identify New Knowledge Not Yet in Memory

From the implementation footprint, extract candidates not present in memory:
- New patterns introduced not in `contexts/memory/patterns/`
- New architectural or technical decisions not in `contexts/memory/decisions/`
- New constraints or conventions applied for the first time

These are **ingestion candidates** — flagged for Discovery to validate and ingest.

---

## Outputs

Written to: `contexts/artefacts/memory-deltas/{id}.memory-delta.md`

```yaml
---
artefact_type: memory-delta
skill: memory-alignment-check
story_id: E01S01
generated_at: YYYY-MM-DD
verdict: ALIGNED | DRIFT_DETECTED | NEW_KNOWLEDGE_FOUND | DRIFT_AND_NEW_KNOWLEDGE
---

## Confirmed Entries

- memory_id: PATTERNS-001
  status: CONFIRMED
  suggested_last_verified_at: YYYY-MM-DD
  suggested_verified_against_story: E01S01
  note: Implementation of X is consistent with stated convention.

## Contradicted Entries

- memory_id: DEC-{N}
  status: CONTRADICTED
  severity: high | medium | low
  description: Memory states [X]. Implementation did [Y]. These are incompatible.
  action_required: Update or invalidate memory entry.

## New Knowledge Candidates

- candidate_id: CANDIDATE-001
  category: architecture | decisions | patterns | project | strategy | domains
  description: New retry pattern introduced in services/api/client.ts — not yet in memory.
  suggested_tags: [api, resilience, patterns]
  ingestion_priority: high | medium | low
```
Downstream consumer: `memory-delta-triage` (`.gaai/core/skills/cross/memory-delta-triage/SKILL.md`) processes these delta files to produce a governed triage verdict before Discovery invokes `memory-ingest`.

---

## Verdict Logic

| Verdict | Condition |
|---|---|
| `ALIGNED` | No contradictions, no new knowledge candidates |
| `DRIFT_DETECTED` | One or more memory entries contradicted by the implementation |
| `NEW_KNOWLEDGE_FOUND` | New knowledge candidates identified, no contradictions |
| `DRIFT_AND_NEW_KNOWLEDGE` | Both contradictions and new knowledge candidates present |

---

## Quality Checks

- Only memory entries intersecting the Story scope are loaded — never full memory
- Confirmed entries include specific evidence from impl-report (not assertions)
- Contradictions describe the exact mismatch — no vague statements
- New knowledge candidates are concrete and grounded in impl-report — not speculative
- No memory is written — this skill produces a report only

---

## Non-Goals

This skill must NOT:
- Write or update any memory file
- Trigger `memory-ingest` directly (only Discovery may do so)
- Scan the full codebase
- Analyse code outside the Story's implementation footprint
- Make product or architectural decisions
- Block or modify the QA verdict

---

## Closed Grandfather List (one-time legacy exemption)

The CI validator (`validate-memory-deltas.sh`, `LEGACY_GRANDFATHERED` array) exempts exactly 21 pre-canonical-schema delta files from the canonical-section-header check. These files predate the three canonical headers and use heterogeneous legacy formats with no single rename rule.

**Policy (non-negotiable):**
- The allowlist **MUST NOT grow** — every new delta produced by this skill MUST include at least one canonical section header (`## Confirmed Entries`, `## Contradicted Entries`, `## New Knowledge Candidates`).
- Allowlist entries **MAY be removed** after the corresponding delta file is triaged by Discovery and moved to `processed/` (which the validator already excludes).

*Authority: see project audit-intake for the originating finding and grandfathered basenames.*