Pg Shadow Implement

pg-shadow-implement — Phase E shadow-implementation runner

This skill operationalizes knowledge/calibration/shadow-implementation-methodology.md as a runnable procedure. Each run produces calibration data about the planner suite's implementation accuracy, NOT a patch we plan to send upstream.

The pairing:

• Phase C calibrated review (pg-patch-review / review-checklist).
• Phase E (this skill) calibrates implementation (pg-feature-plan / pg-implement).

When to use vs not

Inputs

• Thread URL (required) — a https://www.postgresql.org/message-id/... link to the thread's COVER message, or the flat view URL.
• Slug (optional) — short kebab-case name for the run directory (auto-derived from the thread subject if omitted).

Output

Per run, under knowledge/shadow-implementations/<slug>/:

• spec.md (~50-200 LOC) — COVER extraction, context probe, engagement classification.
• plan.md (~200 LOC) — produced by pg-feature-plan.
• notes.md (~100 LOC) — produced by pg-implement if the run reaches Step 3 implementation.
• comparison.md (~150 LOC) — diff vs upstream patch.
• skill-gaps.md (~50 LOC) — methodology / skill improvements surfaced.

Plus (when implementation is attempted): a dev/ branch shadow-<slug>-ours with our patch, and shadow-<slug>-upstream with theirs.

After every 3-5 runs: knowledge/shadow-implementations/gap-catalog.md — the implementation-side counterpart to Phase C's gap-catalog.

Method — seven steps

Step 1 — Pick / validate the target

1. Confirm the thread matches the candidate criteria from shadow-implementation-methodology.md §"Source of features": subject prefix ([PATCH], Proposal:, PoC:, RFC:, etc.); one COVER; at least one attached patch; not yet committed.
2. If the thread doesn't fit (already merged, no patch, multi-thread series with unclear scope), stop and report — don't force.

Step 2 — Spec extraction (COVER only, NOT the patch)

Read the COVER message + any reviewer replies in the thread. Do NOT read or fetch the attached .patch file yet — that's Step 4. Reading the patch before Step 4 contaminates the calibration signal: the shadow loop measures what our planner suite produces from the COVER alone, so any patch-derived knowledge poisons the diff. If you catch yourself wanting to peek, the answer is no — Steps 3-5 will surface the gap explicitly.

M-finding lineage. The M1 … M5 tags throughout Step 2-5 come from the money-fx-exchange shadow run (Phase E run 1), recorded in knowledge/shadow-implementations/money-fx-exchange/skill-gaps.md. They are durable methodology findings:

• M1 — archive-fetch fallback chain (Step 4).
• M2 — posting-date / context-awareness pre-step.
• M3 — pre-emit file:line cite verification (consumed by pg-feature-plan).
• M4 — REJECT as valid plan-stage terminal output.
• M5 — thread-engagement classification (unengaged / acked / debated / contested).

Future shadow runs may add M6+ to this lineage.

Produce knowledge/shadow-implementations/<slug>/spec.md with:

• Frontmatter: slug, thread-url, first-message-url, author, captured-at, captured-anchor, posted-at, shadow-run-status (see status enum below).
• ## Context awareness (M2) — per pg-feature-plan's Context-awareness pre-step (PR #168 adds this). Date, author posture, engagement signal.
• ## What this does — verbatim COVER claim.
• ## Touched subsystems — from knowledge/personas/domain-ownership.md lookup + inferred from the COVER.
• ## Predicted reviewer set — top 5-6 names per knowledge/personas/domain-ownership.md's reviewer column for the touched subsystem.
• ## Author's stated claims — files / behavior / backpatch / tests.
• ## Open questions raised in thread — verbatim reviewer asks, classified per the M5 engagement classification: unengaged / acked / debated / contested.
• ## Phase 0 gates — apply review-checklist Phase 0 reflex gates to the COVER.
• ## REJECT-track decision (M4) — if context-awareness or engagement classification recommends REJECT, name the grade (REJECT-A / REJECT-B) and stop. The deliverable becomes a thread reply per review-checklist Phase 0 REJECT track, recorded in comparison.md instead of a patch.

shadow-run-status enum for the frontmatter:

• SPEC EXTRACTED — Step 2 done, Step 3 not yet started.
• PLAN PRODUCED — Step 3 done.
• IMPLEMENTATION IN PROGRESS — Step 3 implementation underway.
• IMPLEMENTATION DONE — dev/ branch landed.
• COMPARISON DONE — Step 5 emitted comparison.md.
• GAPS LOGGED — Step 6 emitted skill-gaps.md.
• REJECT-A / REJECT-B — REJECT verdict; Steps 3-5 skipped.
• BLOCKED — methodology M1 archive 503, or external dependency missing.

Step 3 — Shadow implementation

Run the planner suite as if the user just asked for this feature:

1. pg-feature-brainstorm against the spec → idea-shaping notes (planning/shadow-<slug>/brainstorm.md).
2. pg-feature-plan against the brainstorm → detailed plan (knowledge/shadow-implementations/<slug>/plan.md, NOT planning/... — shadow runs live in knowledge/).
3. pg-implement against the plan → patch on a dev/ branch shadow-<slug>-ours, per .claude/rules/pg-implement-discipline.md.
4. Per-phase checks (regress + iso + TAP scoped to area).
5. Self-review per pg-patch-review (5 critics including Critic E).

DO NOT look at the upstream patch until Step 3 is complete.

Lighter-weight variant for design-only runs: if the patch is small (~50 LOC) or scope is purely additive, stopping after Step 3 plan + Step 4 fetch + Step 5 design-level comparison is acceptable. Skip Step 3.3-3.5 (no dev/ branch). Record the choice in spec.md's shadow-run-status field. The first two Phase E runs (money-fx-exchange, temp-file-compression) ran in design-only mode.

Step 4 — Ground truth fetch

After our implementation is done:

1. Fetch the latest patch version from the thread: https://www.postgresql.org/message-id/raw/<message-id> for the message text, or the explicit .patch attachment URL.
2. M1 fallback chain if the fetch fails with 503 / network error:
   • Try gitweb mirror via message-id.
   • Try CommitFest patch-set URL if CF# is known.
   • Try archive attachment URL with up to 3 retries.
   • If all fail: proceed with design-level-only comparison and log the unavailability in comparison.md.
3. Apply to a sibling dev/ branch shadow-<slug>-upstream.
4. Record its commit message + scope + file:line surface.

Step 5 — Diff + score

Produce comparison.md. The skeleton (matches the template in shadow-implementation-methodology.md):

---
slug: <slug>
comparison-status: <FULL | DESIGN-LEVEL ONLY (M1 fallback)>
verdict: <grade> (<one-line reason>)
---

## Scope match
| Dimension | Ours | Theirs | Match? |
|---|---|---|---|
| Files touched | <list> | <list> | ✓/✗ |
| LOC | N | M | ✓/✗ within 20% |
| New symbols | <list> | <list> | overlap % |
| Behavior delta | <our claim> | <their claim> | semantic equiv? |

## Design match
- Same partitioning? <Y/N>
- Same data structures / signatures? <Y/N>
- Same invariants honored (INV-* in knowledge/subsystems/)? <Y/N>
- Same hook / extension surface? <Y/N>

## File:line accuracy
- For each file:line cite in our plan: still holds vs upstream? <hit %>

## Missed concerns (theirs raised, ours didn't)
## Novel concerns (ours raised, theirs didn't)
## Reviewer-reflex match
- pg-patch-review Critic E predictions vs actual thread reflexes: diff
## Verdict
- Grade: A / B / C / D / F or REJECT-A / REJECT-B / REJECT-C
- Top 3 skill / corpus gaps surfaced

Scoring rubric. Pick exactly one grade. The A-F track applies when Step 3 produced an implementation; the REJECT-A/B/C track applies when Step 2 terminated at the M4 REJECT decision and the deliverable was a thread reply, not a patch. The two tracks are mutually exclusive (different shadow-output types). Append (design-only) to any grade when the M1 fallback chain failed and Step 5 ran without an upstream patch body — e.g. B (design-only), REJECT-A (design-only).

Disambiguating A vs B: "1-2 design choices diverge" is the B-threshold. Any single design divergence — even one that doesn't break an invariant — moves the grade from A to B. A is reserved for runs where the only differences are style or minor variable naming.

Step 6 — Skill feedback

For each gap surfaced in comparison.md, produce skill-gaps.md. Skeleton (matches money-fx-exchange/skill-gaps.md):

---
slug: <slug>
purpose: Gaps surfaced by this shadow run — input to next skill-creator pass
---

# Skill gaps surfaced by <slug> shadow run

## Gap M<N> — <one-line title>
**Where**: <skill or knowledge doc path>
**Symptom**: <what went wrong / would have gone better>
**Fix**: <1-2 sentence proposed edit>
**Owner skill**: <pg-feature-plan | pg-implement | review-checklist | ...>

(repeat per gap; M-ordinals are unique across the whole run lineage,
not per gap-class — extend the M1-M5 series from money-fx-exchange)

## What this run did NOT surface
<corpus / persona / scenario gaps that did NOT appear — useful negative
signal that things are calibrated>

## Recommendation for next skill-creator pass
<bulleted list keyed to skill-creator-brief.md tiers>

Each gap entry must name:

• Which skill or knowledge doc would have closed the gap if richer.
• A 1-2 sentence proposed change.
• An M<N> ordinal (continues the M1-M5 series from money-fx-exchange — do not reset).

Step 7 — Aggregate (after N runs)

Once 3-5 shadow runs exist, produce knowledge/shadow-implementations/gap-catalog.md — same shape as knowledge/calibration/gap-catalog.md (5-15 actionable items each with hit-rate across runs + skill driver).

Anti-patterns (don't do these)

• Don't read the patch before Step 4. That's the whole point — reading the patch first removes the calibration signal.
• Don't skip the M2 context-awareness probe. It's what surfaces the April-1 / unserious-thread case (money-fx run 1 caught a joke proposal).
• Don't classify unengaged engagement as acked. Reply count alone is misleading; deadpan replies don't validate community endorsement.
• Don't produce a Step 5 grade without Step 4 fetch. If M1 fallback chain fails, the verdict is design-level-only — record this in comparison.md and tag the grade with (design-only).
• Don't move shadow output into planning/. Shadow runs are durable corpus, not WIP planning artifacts. The planning/shadow-<slug>/brainstorm.md from Step 3 is the only exception (the brainstorm skill's hardcoded path).

Boundaries vs other skills

• pg-feature-brainstorm — invoked at Step 3.1; produces planning/shadow-<slug>/brainstorm.md.
• pg-feature-plan — invoked at Step 3.2; consumes the M2/M3/M5-enhanced version from PR #168.
• pg-implement — invoked at Step 3.3 if the run is full-implementation, not design-only.
• pg-patch-review — invoked at Step 3.5 in --self mode for the shadow's own self-review; also at Step 5 to predict reviewer reflexes.
• review-checklist — Phase 0 gates applied at Step 2; REJECT track applied at the M4 decision point.
• memory-keeping — session log of the shadow run goes through this skill at run end.
• meta-commit-style — every artifact commits to the meta repo via this style.

Output volume + cadence

Per run: ~600-800 LOC across 5 docs + (optional) a dev/ branch. Per-run wall time: 3-4 hours for full implementation; ~1-2 hours for design-only.

Cadence:

• 1 run per week initially.
• After 3-5 runs: aggregate gap-catalog.
• Once the catalog stabilises: fire when a major thread lands (not weekly).

Cross-references

• knowledge/calibration/shadow-implementation-methodology.md — the canonical recipe this skill operationalizes. Where they disagree, the methodology doc wins (it's the audit-of-record).
• knowledge/shadow-implementations/README.md — index of runs.
• knowledge/shadow-implementations/money-fx-exchange/ — Phase E run 1 (REJECT-A; surfaced M1-M5).
• knowledge/shadow-implementations/temp-file-compression/ — Phase E run 2 (spec done; plan/comparison deferred to next session).
• knowledge/calibration/gap-catalog.md — Phase C analog the aggregate catalog mirrors.
• .claude/skills/pg-feature-brainstorm/SKILL.md, .claude/skills/pg-feature-plan/SKILL.md, .claude/skills/pg-implement/SKILL.md — the planner suite under test.
• .claude/skills/pg-patch-review/SKILL.md — Critic E supplies the reviewer-reflex predictions Step 5 cross-checks.
• .claude/skills/review-checklist/SKILL.md — Phase 0 gates + M4 REJECT track this skill consumes.
• .claude/rules/pg-implement-discipline.md — the rule the planner suite obeys; this skill exercises that obedience.
• .claude/commands/pg-shadow.md — slash-command wrapper.
• knowledge/personas/archive-participants.md — source of candidate thread authors.