From 82d2614fd436346f529cbabf406a42b2965b80c5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 28 Apr 2026 05:31:46 +0000 Subject: [PATCH] Add capture-before-act rule for user-supplied reference materials MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New AGENTS.md §11 + docs/ai-project-memory.md §User-supplied reference materials: any external reference the user provides during a change (Figma / Canva / Sketch / prototype links / requirement docs / mockups / transcripts / PDFs / URLs the change must conform to) must be persisted to project memory before implementation begins, with URL + fetch date + accessing identity + a substantive summary, not just the URL alone. Closes the recurring failure where a takeover session "ignores the design" because the original reference was Tier 1 (session) memory only and was lost to compression. --- AGENTS.md | 17 ++++++++++++++++ CHANGELOG.json | 6 ++++++ CHANGELOG.md | 4 ++++ docs/ai-project-memory.md | 42 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 69 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 726f112..47ab5d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -140,6 +140,23 @@ The rules are stated as principles, not as exhaustive trope lists, so they remai Full contract: `docs/output-craft-discipline.md` +### 11. User-supplied reference materials must be captured to project memory + +When the user provides external reference materials — design files (Figma / Canva / Sketch / equivalents), prototype links, requirement documents, mockup screenshots, transcripts, PDFs, or any URL or file the change must conform to — the AI **must persist them to project memory before acting on them**. The conversation is Tier 1 (session) memory; URLs and inline file contents that exist only there are lost to context compression and to session break, and a Reviewer or downstream session cannot verify a change against a reference it cannot see. + +Mandatory capture, before implementation begins: + +- **URL-based references** (Figma, Canva, prototype links, externally hosted specs) — record URL + fetch date + accessing identity + a substantive summary of the contents (frames / pages / sections relevant to the change, not just the URL string) into a tracked file under the project's project-memory layout (e.g. `docs/references/.md`, or the equivalent location chosen per `docs/ai-project-memory.md` §Recommended on-disk layout). +- **File-based references** (PDFs, screenshots, design exports, transcripts pasted inline) — persist the file under a tracked path. Cite it from the active manifest's appropriate field. +- **Inline design intent stated in chat** — extract the constraints into a written reference note before the conversation compresses; the chat is not project memory. +- **Cite every captured reference** from the active manifest, plan, or ROADMAP row so downstream roles (Reviewer, takeover sessions) discover it through the artifact, not through scrollback. + +Forbidden: acting on a Figma / Canva / prototype URL the user mentioned without first persisting URL + summary; recording only the URL with no summary (URLs rot and access-control changes — a captured summary survives both); treating "the user pasted the design earlier in the chat" as the persistent record (`docs/ai-project-memory.md` §Anti-patterns — *Conversation treated as SoT*); asking the user to re-paste the same material across sessions because the AI did not persist it the first time. + +This rule has the same severity as the §1 non-fabrication rules: a later citation of "the design says X" against an unpersisted reference is functionally a fabrication, because no one — Reviewer, takeover session, or human auditor — can re-verify it. + +Full contract: `docs/ai-project-memory.md` §User-supplied reference materials. + --- ## Recommended reading order diff --git a/CHANGELOG.json b/CHANGELOG.json index 6540533..8ba1e8e 100644 --- a/CHANGELOG.json +++ b/CHANGELOG.json @@ -4,6 +4,12 @@ "version": "Unreleased", "date": null, "sections": { + "added": [ + { + "title": "`AGENTS.md §11` + `docs/ai-project-memory.md §User-supplied reference materials` — capture-before-act rule for externally provided references", + "body": "new operating-contract rule mandating that any external reference material the user supplies during a change (design files in Figma / Canva / Sketch / equivalents, prototype links, requirement documents, mockup screenshots, transcripts, PDFs, or any URL / file the change must conform to) is **persisted to project memory before implementation begins**, not held in conversation scrollback. Capture protocol: URL references record URL + fetch date + accessing identity + a substantive summary (not the URL alone) under a tracked project-memory path (e.g. `docs/references/.md` or the layout chosen per `docs/ai-project-memory.md §Recommended on-disk layout`); file references are persisted under a tracked path and cited from the active manifest; inline design intent stated in chat is extracted to a written reference note before compression. Closes a recurring failure mode where the second session on a change \"ignores the design\" because the original reference was Tier 1 (session) memory only and was lost to compression or session break — the symptom is functionally a §1 / §9 fabrication, since no Reviewer or takeover session can re-verify \"the design says X\" against a URL that exists only in a previous AI's compressed context. AGENTS.md §11 carries the operating-contract summary; the SoT detail (mandatory capture protocol, forbidden patterns *Act-then-capture* / *Citation-by-URL-only* / *Conversation-as-archive* / *Re-prompting for the same material*, cross-references to `ai-operating-contract.md §4` context hygiene + `§3` evidence quality + `multi-agent-handoff.md §Reviewer`) lives in `docs/ai-project-memory.md` between §What is memory-worthy and §Minimum write-to-disk at session end. Thin-bridges (`CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, `.cursor/rules/*.mdc`, `agents/*.md`) inherit automatically per `docs/file-role-map.md` and carry no new normative content." + } + ], "fixed": [ { "title": "`AGENTS.md §6` Phase-gate discipline summary aligned with SoT", diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a7a042..0ee9826 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ Format inspired by Keep a Changelog; versioning policy in `VERSIONING.md`. ## [Unreleased] +### Added + +- **`AGENTS.md §11` + `docs/ai-project-memory.md §User-supplied reference materials` — capture-before-act rule for externally provided references** — new operating-contract rule mandating that any external reference material the user supplies during a change (design files in Figma / Canva / Sketch / equivalents, prototype links, requirement documents, mockup screenshots, transcripts, PDFs, or any URL / file the change must conform to) is **persisted to project memory before implementation begins**, not held in conversation scrollback. Capture protocol: URL references record URL + fetch date + accessing identity + a substantive summary (not the URL alone) under a tracked project-memory path (e.g. `docs/references/.md` or the layout chosen per `docs/ai-project-memory.md §Recommended on-disk layout`); file references are persisted under a tracked path and cited from the active manifest; inline design intent stated in chat is extracted to a written reference note before compression. Closes a recurring failure mode where the second session on a change "ignores the design" because the original reference was Tier 1 (session) memory only and was lost to compression or session break — the symptom is functionally a §1 / §9 fabrication, since no Reviewer or takeover session can re-verify "the design says X" against a URL that exists only in a previous AI's compressed context. AGENTS.md §11 carries the operating-contract summary; the SoT detail (mandatory capture protocol, forbidden patterns *Act-then-capture* / *Citation-by-URL-only* / *Conversation-as-archive* / *Re-prompting for the same material*, cross-references to `ai-operating-contract.md §4` context hygiene + `§3` evidence quality + `multi-agent-handoff.md §Reviewer`) lives in `docs/ai-project-memory.md` between §What is memory-worthy and §Minimum write-to-disk at session end. Thin-bridges (`CLAUDE.md`, `GEMINI.md`, `.windsurfrules`, `.cursor/rules/*.mdc`, `agents/*.md`) inherit automatically per `docs/file-role-map.md` and carry no new normative content. + ### Fixed - **`AGENTS.md §6` Phase-gate discipline summary aligned with SoT** — the body said "Five rules apply" and listed rules 1–5, while the same paragraph's footnote referenced "the six rules" (per `docs/phase-gate-discipline.md §Ceremony scaling — how the six rules apply per execution mode`). Rule 6 (Phase re-entry protocol) and sub-rule 5a (working-space production discipline) were missing entirely from the consumer summary. The body now reads "Six rules apply" with one-line summaries of sub-rule 5a (under Rule 5) and Rule 6, both citing `docs/phase-gate-discipline.md §Rule N` as the canonical source. The closing "Ceremony scaling" sentence is updated from "These five rules" to "These six rules" to match. No changes to the SoT itself; this is consumer alignment per `CLAUDE.md §5` (cross-cutting term update obligation). diff --git a/docs/ai-project-memory.md b/docs/ai-project-memory.md index 6bb202b..44df7ee 100644 --- a/docs/ai-project-memory.md +++ b/docs/ai-project-memory.md @@ -149,6 +149,48 @@ In one line: **if the next person (human or AI) taking over would get something --- +## User-supplied reference materials + +A specific subclass of memory-worthy content deserves its own discipline because it is the most common silent-drift trigger across sessions: **external reference materials the user provides during the change** — design files (Figma, Canva, Sketch, or equivalents), prototype links, requirement documents, mockup screenshots, transcripts, PDFs, and any URL or file the change must conform to. + +These references pass the §The test for memory-worthiness ("the next person taking over would get something wrong by not knowing this"). They differ from other memory-worthy content along two axes: + +- **They originate outside the repo.** Decisions, scope boundaries, and red lines accumulate inside the workflow; reference materials arrive from external tools (design platforms, document hosts, the user's clipboard) and are not automatically captured by the AI's normal artifacts (manifest, plan, completion report). +- **They live in volatile media.** A design URL is a Tier 1 fact unless persisted; an inline PDF the user pasted is a context-window string that vanishes on compression. Without explicit capture, the reference is gone the moment the session ends. + +### Mandatory capture protocol + +When the user provides any external reference material, **before acting on it**, the AI must: + +1. **For URL-based references** — record the URL, fetch date, accessing identity, and a substantive summary of the contents (frames / pages / sections relevant to the change, not the URL string alone). Save under a tracked path in the project's project-memory layout (e.g. a `docs/references/.md` file, or the equivalent location chosen per §Recommended on-disk layout). +2. **For file-based references** (PDFs, screenshots, design exports, transcripts, mockups pasted inline) — persist the file under a tracked path. Cite it from the active manifest's appropriate field. +3. **For inline design intent stated in chat** — extract the constraints and intent into a written reference note. The conversation will compress; the note will not. +4. **Cite the captured reference** from the active manifest, plan, or ROADMAP row so downstream roles (Reviewer, takeover sessions) discover it through the artifact, not through scrollback. + +The summary is not optional. A bare URL with no extracted contents is functionally a citation-by-link to a moving target — design files are reorganised, access is revoked, hosting providers expire links. The captured summary survives all three failure modes. + +### Why this is a discipline-level rule + +- A Reviewer cannot verify a change against a reference it cannot see (`ai-operating-contract.md` §3 evidence quality requires the reference to be inspectable). +- A downstream session resuming the change cannot re-verify against a URL that exists only in a previous AI's compressed context — the reference becomes an invisible source of silent drift, and the symptoms surface as "the second AI ignored the design." +- Asking the user to re-paste the same material across sessions is itself a §Anti-patterns violation (*Conversation treated as SoT*) and an `ai-operating-contract.md` §7 communication-style failure (asking the user to do work the AI was supposed to do). + +### Forbidden patterns + +- **Act-then-capture.** Beginning implementation against a Figma / Canva / prototype URL before persisting it. Capture is a precondition, not a follow-up. +- **Citation-by-URL-only.** Recording only the URL with no summary. URLs rot and access-control changes; a captured summary survives both. +- **Conversation-as-archive.** Treating "the user pasted the design earlier in the chat" as the persistent record. The conversation is Tier 1 memory. +- **Re-prompting for the same material.** Asking the user to re-paste a reference they already provided in a previous session because the AI did not persist it the first time. + +### Relationship to other rules + +- [`AGENTS.md`](../AGENTS.md) §11 — the operating-contract summary; this section is its source of truth. +- [`ai-operating-contract.md`](ai-operating-contract.md) §4 Context hygiene — captures the general rule that important facts must be written to files; this section names the specific class of facts that fail the discipline most often. +- [`ai-operating-contract.md`](ai-operating-contract.md) §1 Honest uncertainty reporting + §9 Non-fabrication list — without the captured reference, every later citation of "the design says X" becomes a fabrication or an uncited assumption. +- [`multi-agent-handoff.md`](multi-agent-handoff.md) §Reviewer — the Reviewer's right to verify references is contingent on capture; an unpersisted reference is not reviewable. + +--- + ## Minimum write-to-disk at session end Before the session ends, or before compression hits, the AI must ensure the following have been written to files: