Screenshot verification and plan Context completeness

Where it landed

Two independent fixes landed in one session, unrelated to each other beyond sharing a source: a plugin/skills review run earlier against an external article on agent-prompting technique.

social-media-tools's shared Playwright screenshot pipeline gained a post-capture verification step — it checked the DOM was ready before capture but never checked the output file after, so a blank PNG still counted as success. Committed and pushed (0bedc78, branch claude/project-optimization-review-595e98).

plan-agent's implementation-plan and build-proposal skills, plus the personal global plan-mode skeleton, got an explicit "no follow-up question" completeness bar added to their ## Context section guidance. Still uncommitted in the working tree.

Where things live, and how they call

Screenshot pipeline

kit/plugins/social-media-tools/references/rendering-pipeline.md is a single shared reference, not duplicated per skill. Ten SKILL.md files read it: share-code, share-react, share-github, share-project, share-session, share-selection, share-explanation, share-blog, share-video, and one more matched by the same grep. One file change reaches all ten with no per-skill edit.

Step 5 is new. A blank or truncated capture now routes to Fallback instead of reaching Deliver.

Plan Context sections

Three independent copies of the same guidance, no shared code path between them:

• kit/plugins/plan-agent/skills/implementation-plan/guidelines/section-catalog.md — the canonical section definitions implementation-plan's Workflow Step 2.2 reads before drafting a spec.
• kit/plugins/plan-agent/skills/implementation-plan/reference/SKELETON.md — the copyable starter the same step also reads.
• kit/plugins/plan-agent/skills/build-proposal/references/artifact-shape.md — build-proposal's equivalent: both the prose section-order description (item 4) and its own copyable Skeleton block.
• ~/.claude/reference/SKELETON.md (outside this repo) — the global starter ~/.claude/rules/plan-mode.md Step 2 tells any Claude Code session to copy, in any project.

Worth knowing before touching any of these again: implementation-plan already has a ## Decisions section, and build-proposal already has Locked & resolved decisions — both exist specifically so "a resumed session reads this instead of re-deriving" (verbatim from section-catalog.md). Context is the why; Decisions/Locked-decisions is the settled how. Don't merge them.

Not modified, but load-bearing if extending verification-gate patterns elsewhere: kit/plugins/plan-agent/skills/build/references/completion-gates.md is this repo's reference implementation of a mandatory, bounded, escalate-rather-than-fake-success verification gate — the pattern the screenshot check is a lightweight instance of.

What was decided, and why

What was weighed and lost

• Rejected: pixel-level screenshot verification. More accurate than byte count, but needs an image-processing dependency not currently in the pipeline. Revisit if the 5KB heuristic misfires in practice — the ponytail: comment in rendering-pipeline.md names this as the upgrade path.
• Rejected: a retry-on-failure loop for the screenshot step, mirroring plan-agent:build's 3-try fix loop. Out of scope for what was asked; on any Step 5 failure the pipeline falls back to the same single Fallback message it already used for other failure modes (Playwright unavailable, capture failure) — consistent, not new.
• Rejected: rewriting the Context section definitions wholesale in implementation-plan/build-proposal. Would have duplicated or blurred what ## Decisions/Locked & resolved decisions already do. A one-sentence addition was chosen once the existing design was understood.
• Rejected: applying "unpack jargon on first use" broadly across plan-mode/plan-agent writing style. Conflicts on purpose with the existing "precise names over plain words" rule for an expert-engineer-only reader. Scoped out entirely — not partially applied anywhere.

Tried, abandoned, and gotchas

• A skill's top-level SKILL.md workflow steps can undersell how complete its guidelines//references/ files already are. The Context-section gap was originally diagnosed from implementation-plan/SKILL.md's one-line summary ("Optional by judgment: Context…") without reading guidelines/section-catalog.md or guidelines/right-sizing.md first. Those turned out to already solve the described problem, just under a different section name. Read the deeper files before diagnosing a gap in a mature skill.
• One shared reference file can back many skills in this plugin family. social-media-tools/references/rendering-pipeline.md is read by ten separate SKILL.md files; the fix didn't need touching any of them. Worth checking for a shared reference before assuming per-skill duplication is needed.
• No automated test exercises the Playwright screenshot pipeline end-to-end — it needs a live browser, which this session didn't have. What ran instead (test-no-shell-expansion.sh, test-react-card-smoke.sh, test-share-react-registration.sh) confirms no shell-expansion or template-registration regression, but none execute the new Step 5 logic against a real capture. A real coverage gap, not just an unexercised edge case.

What ran, and what didn't

• git fetch origin && BASE_REF=main node scripts/check-plugin-versions.mjs — run after each version bump (social-media-tools 2.23.0→2.23.1, plan-agent 9.4.1→9.4.2). pass
• python3 -c "json.load(...)" on marketplace.json after each edit — valid JSON. pass
• tests/plugins/test-no-shell-expansion.sh — confirms the new $SAVE_PATH_PNG/$SIZE vars don't introduce a ${VAR}-style expansion (this repo's Bash tool rejects those outright). pass
• tests/social-media-tools/test-react-card-smoke.sh, test-share-react-registration.sh pass
• tests/plugins/test-build-proposal.sh, test-proposal-prompt-pipeline.sh, test-goal-prompt.sh, test-resources-section.sh, test-write-prompt-proposal-type.sh — pass, none assert on the new Context prose specifically (expected — prose-only, no structural or parser-visible effect). pass
• tests/plugins/test-humanized-skeleton.sh — run, passed, confirmed irrelevant on inspection (checks renderer HTML output, not these guideline files). n/a
• Knowingly untested: the screenshot verification logic was never run against a real Playwright capture — no live browser in this session. The 5KB threshold is unverified against an actual blank-vs-populated card pair. untested

Open items

Grouped by area