Back-Port Instance Fixes Into Their Scaffold/Generator
When to Use This Skill
| Situation |
Skill |
Fixing, reviewing, or auditing a file a generator emitted — cookiecutter/copier template, justfile new-* recipe, a *-scaffold skill, a "copy the example app" doc |
This skill — patch the generator in the same sweep |
| Repeated code inside one codebase, with no generator behind it |
code-quality-plugin:dry-consolidation |
| Auditing a whole fleet of generated instances against their template |
The inverse direction — .claude/rules/generated-fleet-drift.md; an instance may legitimately be ahead of the template, so never auto-apply template → instance |
When fixing something that was generated — a site scaffolded by a
justfile recipe, a repo from a cookiecutter template, a config from a
new-* skill — check whether the bug came from the generator, and if
so, fix the generator in the same sweep. A fix applied only to the
deployed instance leaves every future generation broken in the same
way, and the gap is invisible until the next person scaffolds.
The failure mode
Canonical case (FVH sites monorepo, 2026-06): two PRs fixed the
deployed example-static site — service.targetPort: 8080 for the
non-root nginx image, numeric runAsUser for Kyverno — but the
just new-site template that had produced those broken values was
never touched. Every subsequently scaffolded site would have shipped
with chart-default port-80 probes against an 8080 listener: pod never
Ready, stuck Progressing, no error anywhere. Found and back-ported
only weeks later during a readiness audit (sites#11).
The shape is always the same:
- An instance misbehaves; someone fixes the instance. PR merges, done.
- The generator still emits the pre-fix content.
- The next generation reproduces the bug — often for someone without
the context of fix #1.
The rule
- When fixing a generated artifact, ask: "did the generator produce
this bug?" If yes, patch the generator template in the same PR (or an
immediately linked one) — not as a someday follow-up.
- When reviewing a fix to a known-scaffolded file (e.g.
deploy/values.yaml in a monorepo with a new-* recipe, anything
under a directory a cookiecutter emits), check the template for the
same defect before approving.
- When auditing a scaffold for readiness, diff the template's output
against the oldest working instance — accumulated instance-only fixes
show up as the delta.
Where generators hide
- justfile
new-* recipes with heredoc templates
cookiecutter/ directories and copier templates- Claude skills that scaffold (
*-scaffold, configure-*)
- "Copy the example app" docs — the example is the generator; fixes to
forks of it don't propagate back
Verify
After back-porting, generate a throwaway instance and diff it against
the fixed real instance — the relevant blocks should match:
just new-site zz-smoke-test
diff <(yq ... sites/zz-smoke-test/deploy/values.yaml) <(yq ... sites/example-static/deploy/values.yaml)
Clean up the throwaway (including any registry/config files the recipe
mutated) before committing.
Rationale
This is DRY applied to provenance: the template is the source of truth
for new instances, so a fix that skips it creates a silently diverging
copy. The cost asymmetry is stark — back-porting at fix time is one
extra edit with full context in hand; discovering it later costs a
broken deploy, a re-diagnosis from scratch, and usually a different
person's afternoon.
1---
2name: code-scaffold-backport
3description: Back-port an instance fix into the generator that produced it — cookiecutter, scaffold, `new-*` recipe. Use when fixing, reviewing, or auditing a generated file.
4allowed-tools: Read, Grep, Glob, Edit, Bash, TodoWrite
5created: 2026-08-19
6modified: 2026-08-19
7reviewed: 2026-08-19
8---
9
10# Back-Port Instance Fixes Into Their Scaffold/Generator
11
12## When to Use This Skill
13
14| Situation | Skill |
15|-----------|-------|
16| Fixing, reviewing, or auditing a file a generator emitted — cookiecutter/copier template, justfile `new-*` recipe, a `*-scaffold` skill, a "copy the example app" doc | **This skill** — patch the generator in the same sweep |
17| Repeated code inside one codebase, with no generator behind it | `code-quality-plugin:dry-consolidation` |
18| Auditing a whole fleet of generated instances against their template | The inverse direction — `.claude/rules/generated-fleet-drift.md`; an instance may legitimately be *ahead* of the template, so never auto-apply template → instance |
19
20When fixing something that was *generated* — a site scaffolded by a
21justfile recipe, a repo from a cookiecutter template, a config from a
22`new-*` skill — check whether the bug came from the generator, and if
23so, fix the generator **in the same sweep**. A fix applied only to the
24deployed instance leaves every future generation broken in the same
25way, and the gap is invisible until the next person scaffolds.
26
27## The failure mode
28
29Canonical case (FVH `sites` monorepo, 2026-06): two PRs fixed the
30deployed `example-static` site — `service.targetPort: 8080` for the
31non-root nginx image, numeric `runAsUser` for Kyverno — but the
32`just new-site` template that had produced those broken values was
33never touched. Every subsequently scaffolded site would have shipped
34with chart-default port-80 probes against an 8080 listener: pod never
35Ready, stuck `Progressing`, no error anywhere. Found and back-ported
36only weeks later during a readiness audit (sites#11).
37
38The shape is always the same:
39
401. An instance misbehaves; someone fixes the instance. PR merges, done.
412. The generator still emits the pre-fix content.
423. The next generation reproduces the bug — often for someone without
43 the context of fix #1.
44
45## The rule
46
47- **When fixing a generated artifact**, ask: "did the generator produce
48 this bug?" If yes, patch the generator template in the same PR (or an
49 immediately linked one) — not as a someday follow-up.
50- **When reviewing a fix to a known-scaffolded file** (e.g.
51 `deploy/values.yaml` in a monorepo with a `new-*` recipe, anything
52 under a directory a cookiecutter emits), check the template for the
53 same defect before approving.
54- **When auditing a scaffold for readiness**, diff the template's output
55 against the oldest working instance — accumulated instance-only fixes
56 show up as the delta.
57
58## Where generators hide
59
60- justfile `new-*` recipes with heredoc templates
61- `cookiecutter/` directories and copier templates
62- Claude skills that scaffold (`*-scaffold`, `configure-*`)
63- "Copy the example app" docs — the example *is* the generator; fixes to
64 forks of it don't propagate back
65
66## Verify
67
68After back-porting, generate a throwaway instance and diff it against
69the fixed real instance — the relevant blocks should match:
70
71```
72just new-site zz-smoke-test
73diff <(yq ... sites/zz-smoke-test/deploy/values.yaml) <(yq ... sites/example-static/deploy/values.yaml)
74```
75
76Clean up the throwaway (including any registry/config files the recipe
77mutated) before committing.
78
79## Rationale
80
81This is DRY applied to provenance: the template is the source of truth
82for new instances, so a fix that skips it creates a silently diverging
83copy. The cost asymmetry is stark — back-porting at fix time is one
84extra edit with full context in hand; discovering it later costs a
85broken deploy, a re-diagnosis from scratch, and usually a different
86person's afternoon.
laurigates