record-project-memory — pekral/arch-app-services

## Constraints - Apply `@rules/compound-engineering/general.mdc` *Compound Memory (per project)* — this skill is the write side of that rule; it owns the promotion bar, the curation pass, and the file convention defined there. - Apply `@rules/git/general.mdc` - **Write-only to the memory file.** This skill modifies exactly one file: `docs/memory/PROJECT_MEMORY.md` in the project being worked on. It never edits production code, tests, configuration, `CLAUDE.md`, or `.cursor/rules/project.mdc`. - **Never record secrets, credentials, tokens, or PII** — apply the same prohibition the security rules apply to logs and tracker comments. When a lesson can only be stated with a secret, generalize it until the secret is gone or drop the entry. - **Per-project only.** The memory file lives in the target project, never in this shared rules package. Never write a project lesson into `rules/**` as a global rule. - Output must be in English (the memory file is a code artifact, like `CLAUDE.md`). ## Use when - A `@skills/resolve-issue` or `@skills/process-code-review` run has converged (review loop at 0 Critical / 0 Moderate) and is about to publish its final report. - An orchestrating run reaches its final report after the convergence gate. - The user explicitly asks to record a lesson into project memory. Do **not** run this skill mid-task, before convergence, or for a task that produced no durable lesson. ## Inputs - `CONVERGED_CONTEXT` — required. The converged task context: what was implemented/fixed, the review findings that recurred, the wrong turns taken, and the design decisions made. The orchestrator passes this from the shared brief; a skill passes its own run context. - `SOURCE_REF` — required. The PR / issue link to record in each entry's `Source:` field. - `AGENT_ROLE` — optional. The role writing this entry: `orchestration`, `analysis`, `implementation`, `review`, or `shared`. When omitted, defaults to `shared`. Written as the `Role:` field of every entry produced in this invocation. Pass the caller's own role — do not guess. ## Required approach ### 1. Locate (or plan) the memory file - Target `docs/memory/PROJECT_MEMORY.md` in the project being worked on. - If it does not exist, plan to create it with a one-line index header (`# Project memory — <project>`). Creating it is allowed; this is the file's first write. - If the project demonstrably has no `docs/` tree and refuses to grow one, fall back to the project's existing learnings / decision-log file per `@rules/compound-engineering/general.mdc`. Never fall back to `CLAUDE.md` or `.cursor/rules/project.mdc` themselves. ### 2. Extract candidate lessons from the converged context List every candidate lesson the task surfaced: a recurring review finding, a non-obvious bug cause, a rejected approach, an architectural decision, or the canonical "this kind of change belongs in an existing part of the system, not a new abstraction" insight. ### 3. Apply the promotion bar (all three gates must pass) Keep a candidate only when it clears **all** of: 1. **Recurs beyond this task** — it generalizes to future work, not a one-off detail of this issue. 2. **Cost real effort to discover** — non-obvious, surprising, or learned after a wrong turn. 3. **Not already captured** — not already obvious from the code, the tests, the git history, or an existing rule. Drop every candidate that fails any gate. If **no** candidate clears the bar, record nothing and report `no entry: nothing cleared the promotion bar` — a trivial task writes nothing. ### 4. Format each surviving lesson One entry per lesson, in the greppable format from the rule: ``` ### <slug> — <one-line lesson> - Trigger: <the recurring situation that makes this lesson apply again> - Rule: <the decision / what to do next time> - Example: <a concrete pointer: file / area / symbol> - Source: <PR / issue link> Added: <YYYY-MM-DD> - Role: <orchestration | analysis | implementation | review | shared> ``` `<slug>` is kebab-case and unique within the file. `Added:` is today's date. `Role:` is the value of the `AGENT_ROLE` input (defaults to `shared` when not provided). Strip any secret / credential / token / PII before writing. ### 5. Curation pass (before appending) Read the existing file and curate so it stays small and non-redundant: - **Dedup** — if an equivalent entry exists (same or very similar slug / lesson), do not add a duplicate; strengthen the existing entry only when the new occurrence adds a sharper trigger or example. - **Supersede** — when a new lesson replaces or contradicts an older entry, update (or mark superseded) the old one instead of keeping both. - **Prune** — remove entries whose referenced code was removed or whose lesson was promoted into a real `rules/**` file. - **Soft cap** — when the file grows large, consolidate related entries rather than letting it sprawl. - **Role dedup** — when deduplicating, consider entries with the same slug across different `Role:` values: if both `implementation` and `shared` carry the same lesson, keep the `shared` one and remove the role-specific one. Never widen a role-specific entry to `shared` unless the lesson genuinely applies across all roles. ### 6. Write and report - Apply the curated changes to the memory file (append new entries, edit/remove superseded or pruned ones). - Report in conversation: the slugs added, edited, pruned, and the count that failed the promotion bar — so the convergence handoff records what memory changed. ## Done when - Every candidate lesson was run through the three-gate promotion bar. - Surviving lessons were written to `docs/memory/PROJECT_MEMORY.md` in the entry format, after the curation pass deduped/superseded/pruned. - No secrets, credentials, tokens, or PII were written. - Only the memory file was modified — no production code, tests, `CLAUDE.md`, or `.cursor/rules/project.mdc`. - The report lists the slugs added/edited/pruned, or states `no entry: nothing cleared the promotion bar`. ## Output Humanization - Use [blader/humanizer](https://github.com/blader/humanizer) for all skill outputs to keep the text natural and human-friendly.

Constraints

Apply @rules/compound-engineering/general.mdc Compound Memory (per project) — this skill is the write side of that rule; it owns the promotion bar, the curation pass, and the file convention defined there.
Apply @rules/git/general.mdc
Write-only to the memory file. This skill modifies exactly one file: docs/memory/PROJECT_MEMORY.md in the project being worked on. It never edits production code, tests, configuration, CLAUDE.md, or .cursor/rules/project.mdc.
Never record secrets, credentials, tokens, or PII — apply the same prohibition the security rules apply to logs and tracker comments. When a lesson can only be stated with a secret, generalize it until the secret is gone or drop the entry.
Per-project only. The memory file lives in the target project, never in this shared rules package. Never write a project lesson into rules/** as a global rule.
Output must be in English (the memory file is a code artifact, like CLAUDE.md).

Use when

A @skills/resolve-issue or @skills/process-code-review run has converged (review loop at 0 Critical / 0 Moderate) and is about to publish its final report.
An orchestrating run reaches its final report after the convergence gate.
The user explicitly asks to record a lesson into project memory.

Do not run this skill mid-task, before convergence, or for a task that produced no durable lesson.

Inputs

CONVERGED_CONTEXT — required. The converged task context: what was implemented/fixed, the review findings that recurred, the wrong turns taken, and the design decisions made. The orchestrator passes this from the shared brief; a skill passes its own run context.
SOURCE_REF — required. The PR / issue link to record in each entry's Source: field.
AGENT_ROLE — optional. The role writing this entry: orchestration, analysis, implementation, review, or shared. When omitted, defaults to shared. Written as the Role: field of every entry produced in this invocation. Pass the caller's own role — do not guess.

Required approach

1. Locate (or plan) the memory file

Target docs/memory/PROJECT_MEMORY.md in the project being worked on.
If it does not exist, plan to create it with a one-line index header (# Project memory — <project>). Creating it is allowed; this is the file's first write.
If the project demonstrably has no docs/ tree and refuses to grow one, fall back to the project's existing learnings / decision-log file per @rules/compound-engineering/general.mdc. Never fall back to CLAUDE.md or .cursor/rules/project.mdc themselves.

2. Extract candidate lessons from the converged context

List every candidate lesson the task surfaced: a recurring review finding, a non-obvious bug cause, a rejected approach, an architectural decision, or the canonical "this kind of change belongs in an existing part of the system, not a new abstraction" insight.

3. Apply the promotion bar (all three gates must pass)

Keep a candidate only when it clears all of:

Recurs beyond this task — it generalizes to future work, not a one-off detail of this issue.
Cost real effort to discover — non-obvious, surprising, or learned after a wrong turn.
Not already captured — not already obvious from the code, the tests, the git history, or an existing rule.

Drop every candidate that fails any gate. If no candidate clears the bar, record nothing and report no entry: nothing cleared the promotion bar — a trivial task writes nothing.

4. Format each surviving lesson

One entry per lesson, in the greppable format from the rule:

### <slug> — <one-line lesson>
- Trigger: <the recurring situation that makes this lesson apply again>
- Rule:    <the decision / what to do next time>
- Example: <a concrete pointer: file / area / symbol>
- Source:  <PR / issue link>   Added: <YYYY-MM-DD>
- Role:    <orchestration | analysis | implementation | review | shared>

<slug> is kebab-case and unique within the file. Added: is today's date. Role: is the value of the AGENT_ROLE input (defaults to shared when not provided). Strip any secret / credential / token / PII before writing.

5. Curation pass (before appending)

Read the existing file and curate so it stays small and non-redundant:

Dedup — if an equivalent entry exists (same or very similar slug / lesson), do not add a duplicate; strengthen the existing entry only when the new occurrence adds a sharper trigger or example.
Supersede — when a new lesson replaces or contradicts an older entry, update (or mark superseded) the old one instead of keeping both.
Prune — remove entries whose referenced code was removed or whose lesson was promoted into a real rules/** file.
Soft cap — when the file grows large, consolidate related entries rather than letting it sprawl.
Role dedup — when deduplicating, consider entries with the same slug across different Role: values: if both implementation and shared carry the same lesson, keep the shared one and remove the role-specific one. Never widen a role-specific entry to shared unless the lesson genuinely applies across all roles.

6. Write and report

Apply the curated changes to the memory file (append new entries, edit/remove superseded or pruned ones).
Report in conversation: the slugs added, edited, pruned, and the count that failed the promotion bar — so the convergence handoff records what memory changed.

Done when

Every candidate lesson was run through the three-gate promotion bar.
Surviving lessons were written to docs/memory/PROJECT_MEMORY.md in the entry format, after the curation pass deduped/superseded/pruned.
No secrets, credentials, tokens, or PII were written.
Only the memory file was modified — no production code, tests, CLAUDE.md, or .cursor/rules/project.mdc.
The report lists the slugs added/edited/pruned, or states no entry: nothing cleared the promotion bar.

Output Humanization

Use blader/humanizer for all skill outputs to keep the text natural and human-friendly.