ai-context-engineering-for-qa: Skill for Claude Code

/improve-context-from-sessions — Behavioral Retrospective

ROLE: turns corrections, tool-drift, and validated approaches from the live dialog into context patches. NEVER generates new skills (→ /init-skill).

Trigger: completion signal ("done", "shipped", "merge", "готово") → ASK "Run /improve-context-from-sessions to capture learnings?". Wait for consent. NO auto-fire.

SECOND trigger — BEFORE the artifact leaves the machine, not after: about to publish outward-facing work into a repo, tracker, or board you do not own. Mine the corpus for the gate that already covers it and run that gate FIRST. A retrospective that fires only on completion learns the lesson after the cost is paid; a draft killed at publication time has already burned the whole drafting session.

Invariants (BANNED to violate)

• Surgical Edit ONLY. Wholesale rewrite = BANNED.
• ONE pool, ONE apply. Collect EVERY accepted delta, then apply and commit them together. BANNED: apply a batch → keep mining → apply again. Each apply re-injects the whole corpus at the next context refresh, so N applies cost N × that. Re-run python3 scripts/context-check.py AFTER the pool, before the commit.
• Terse rule style for rules/** + SKILL.md + JIT pointers ONLY. docs/** = human-prose OK. Style spec: docs/terse-rule-style.md.
• NO new-skill generation (handoff → /init-skill).
• Silent corpus edits = BANNED. ASK before any rules / CLAUDE.md / docs write.
• ALREADY-COVERED test — run it per candidate, BEFORE the patch card. Grep CLAUDE.md + rules/** + the owning SKILL.md for the behaviour, not the wording. A rule that already exists AND is correct AND was simply ignored = NO patch: a fourth phrasing of the same rule buys nothing and costs every turn. Dedup (Step 3) catches a textual twin; this catches the live rule that fired and lost. Report it as "covered by <path>:<line>, model ignored it" — that is a hook or gate question, not a corpus edit.
• SCOPE (warm vs cold): THIS skill writes POINT DELTAS into EXISTING rules/*.md / CLAUDE.md (a BANNED / REQUIRE / TRIGGER line). ALSO IN SCOPE: ONE small new docs/*.md (single focused pattern) + its 1-line JIT pointer — create directly, NO handoff. OUT of scope (→ HANDOFF patch-card, action Run /improve-project-context): MULTI-file change, evacuate block → docs/, repurpose a file, file grew or shrank significantly. This skill FINDS structure-at-scale; improve-project-context EDITS it.
• CONTEXT-MAP sync: created / renamed / resized a context file → UPDATE context-map.md IMMEDIATELY in the same run. Cannot locate the map, or a multi-file resync is needed → append the recommendation "run /improve-project-context to resync". BANNED: leave the map drifted silently.
• PLACEMENT: rule unique-to-project AND useful-to-colleagues → <repo>/.claude/ (git-shared). Global rule OR personal preference → ~/.claude/ (CLAUDE.md / rules / docs).
• SHRINK SKILL.md over 300: TWO levers, in order — (1) EXTRACT blocks (examples, algorithms, tables, rationale) → references/ (JIT, 0 start-cost); (2) THEN compress remaining prose per docs/terse-rule-style.md. Extract beats compress.
• COMPRESS prose-heavy CLAUDE.md / rules/*.md over budget → RECOMMEND a compress pass per docs/terse-rule-style.md. Other .md → softer recommend, only if token-pressured.