context-commonization-review
Reviews cross-variant docs/<variant>.context.md duplication and promotes genuinely shared content into the common docs/context.md (ADR-0050 Part 3). Use when: after scaffolding a new variant, on a periodic cadence (every 5 new variants or quarterly, whichever first), or on-demand when asked to check for or reduce context.md duplication across variants.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- context-commonization-review
- owner
- architect
- scope
- workspace
- status
- active
- version
- 1.1.0
- metadata
- { "type": "process", "triggers": [ "context commonization review", "variant context duplication", "commonization review", "context.md duplication review", "context.md commonization" ] }
- relates_to
- [ { "type": "follows", "skill": "promote-variant" }, { "type": "follows", "skill": "meeting-facilitation" } ]
- description
- Reviews cross-variant docs/<variant>.context.md duplication and promotes genuinely shared content into the common docs/context.md (ADR-0050 Part 3). Use when: after scaffolding a new variant, on a periodic cadence (every 5 new variants or quarterly, whichever first), or on-demand when asked to check for or reduce context.md duplication across variants.
- l2_propagate
- false
- last_reviewed
- 1794096000000
03 SKILL.md 正文
Skill: context-commonization-review
When to Use
- Immediately after scaffolding a new variant (
create-variantskill) — a natural checkpoint to check whether the new variant'sdocs/<variant>.context.mdduplicates existing patterns. - At minimum every 5 new variants or once per quarter since the last review, whichever comes first (ADR-0050 Part 3) — variant count, not just calendar time, drives duplication risk.
- On-demand, whenever asked to look for or reduce
docs/context.md/docs/<variant>.context.mdduplication.
This skill is the execution half of a two-part mechanism: scripts/audit.ts's
checkVariantContextCommonization() is the detection half (always runs, WARN-only).
Step-by-Step Procedure
1. Detect candidates
bun scripts/audit.ts 2>&1 | grep "Context commonization candidate"
Each line names a section heading, the overlap percentage, and which variants are involved
— e.g. "git / pr workflow" section is >50% similar (83-100% overlap) across 6/10 variants: ....
2. Decide, per candidate (architect judgment — not automatable)
For each flagged heading, per ADR-0050 Part 3's criteria:
| Situation | Decision |
|---|---|
| Shared by nearly all variants, content is genuinely identical or should be | Promote to docs/context.md |
| Shared by only a subset of variants (e.g. a domain cluster) | Extract into a shared skill or docs/_common/ reference those variants opt into — do not bloat docs/context.md for variants that don't need it |
| Similar today by coincidence, variants expected to diverge later | Leave alone |
| High overlap % but with a meaningful per-variant difference (e.g. a different commit-type convention, a different threshold) | Do not promote as-is — either exclude the diverging variant from the promotion, or conclude the sections aren't actually the same thing despite the heading match |
scripts/promote-context-section.ts (step 3) always prints a line-level diff against the
canonical source before writing anything — read it. A high overlap percentage is a hint, not
a verdict; text that reads as "83% similar" can still carry a deliberate, load-bearing
difference (verified in practice: a git / pr workflow promotion attempt across 6 variants
found co-security used /sync "security: ..." where the others used /sync "feat: ..."
— textually close, semantically not interchangeable).
3. Execute a promotion
bun scripts/promote-context-section.ts \
--heading "<heading text, exactly as it appears in audit.ts's output>" \
--variants co-a,co-b,co-c \
[--source <variant>] # which variant's text becomes canonical (default: first listed)
[--after-heading "<text>"] # where in docs/context.md to insert (default: before Lifecycle Management)
[--dry-run] # always run this first
Review the dry-run output — the per-variant content preview and any divergence warnings —
before re-running without --dry-run. The script:
- Inserts the canonical section into
templates/common/docs/context.mdand bumps its version footer - Removes the section from each listed variant's
templates/<variant>/docs/<variant>.context.md - Does not decide anything and does not touch already-scaffolded projects (see step 4)
Fixed 2026-09-22 — nested ### subsections are no longer dropped. Earlier versions
of the tool removed the promoted section with a regex that stopped at the next #{2,3}
heading, so if the promoted ## section had a nested ### subsection, that subsection was
excluded from both the removal (left behind as an orphaned, parent-less duplicate in the
variant file) and the canonical content copied into docs/context.md (never appeared
there either) — real content loss if no other copy of that subsection existed elsewhere in
the file. Hit in practice promoting "Scripts" (### Hybrid Scripting nested underneath):
7 variant files were left with an orphaned duplicate, and co-consult/co-export
genuinely lost the content since neither had a second copy elsewhere. Fixed in
promote-context-section.ts v1.1.0 (nesting-aware spans, helpers/context-sections.ts
v1.6.0): a promoted ## section now carries its ### children into docs/context.md AND
removes them from every variant file; fenced # lines never terminate a section. The
dry-run preview notes when a candidate section includes nested subsections.
4. Handle already-scaffolded projects
Removing a section from templates/<variant>/docs/<variant>.context.md only fixes future
scaffolds (new-project.ts, create-l3-scaffold.ts) and stops audit.ts from re-flagging the
template. Existing Projects/*/docs/<variant>.context.md files keep the old duplicated text
— there is no automated cleanup path for this (the file isn't a managed-block merge target, so
upgrade-project.ts can't safely delete arbitrary content from it). Either:
- manually remove the now-redundant section from each affected existing project, or
- accept the duplication there until an unrelated future edit touches that section.
Then, for each existing project of the affected variants, pick up the promoted content into
docs/context.md:
bun scripts/upgrade-project.ts <project-path> --variant <variant> --dry-run
5. Extraction path (subset-shared content)
When step 2 decides a candidate should become a shared skill instead of promoting to
docs/context.md: create skills/<name>/SKILL.md with the shared content, update the affected
variants' agents/pm.md or AGENTS.md to reference it, then manually remove the duplicated
prose from each affected variant's docs/<variant>.context.md (promote-context-section.ts
only targets docs/context.md as the promotion destination — it's not a general dedup tool for
skills, since skill placement/wiring per variant needs its own review).
6. Verify and log
bun scripts/audit.ts # the promoted heading should no longer appear as a candidate
Log the decision and rationale in the session's memory/YYYY-MM-DD.md — this is the audit
trail ADR-0050 Part 3 relies on for "why was this promoted/left alone" questions later.
See Also
- ADR-0050 Part 3 (Variant Script Inheritance and Golden-Reference SSOT — Context Commonization Review) — full rationale, thresholds, and open questions
templates/common/docs/context.md§ Lifecycle Management § Context Commonization Reviewskills/upgrade-project/SKILL.md— how promoteddocs/context.mdcontent reaches existing projectsskills/create-variant/SKILL.md— the natural trigger point after scaffolding a new variantdocs/governance/variant-contract.md§ Context.md Structure Standard (validate-templates.tsCheck WS-09) — a related but distinct concern: this skill promotes/dedups content that's duplicated across variants; WS-09 instead enforces that every variant'sdocs/<variant>.context.mdhas the same top-level structure (slot presence + order), regardless of whether the content in each slot is shared or variant-specific. Content standardization was explicitly considered and rejected during WS-09's design — see that doc for why.
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.