Skip to content

docs: add verbatim constants block to eliminate agent transcription errors#20

Open
eralpozcan wants to merge 1 commit intoParthJadhav:mainfrom
eralpozcan:fix/constants-reference-block
Open

docs: add verbatim constants block to eliminate agent transcription errors#20
eralpozcan wants to merge 1 commit intoParthJadhav:mainfrom
eralpozcan:fix/constants-reference-block

Conversation

@eralpozcan
Copy link
Copy Markdown
Contributor

@eralpozcan eralpozcan commented Apr 25, 2026

Problem

All critical numeric values — canvas dimensions, iPhone mockup measurements, export sizes, frame ratios, and width formula functions — were scattered across several subsections of Step 5. Agents had to read, interpret, and retype them. This is non-deterministic: agents occasionally produce wrong resolutions or misaligned device frames, and Apple/Google may reject the output silently.

Solution

Consolidate every verified constant into a single "copy this block verbatim" TypeScript block at the top of Step 5. Agents paste it as-is; no derivation or reasoning needed. Transcription errors on constants are no longer possible.

This addresses #17 via a different approach than proposed. The issue suggested replacing SKILL.md with a full starter Next.js project — we chose not to: a committed Next.js project requires ongoing dependency maintenance, introduces IDE type errors when viewed outside a project context, and shifts the repo from a skill provider into a code project. The verbatim constants block achieves the same correctness guarantee (agents can no longer mistype critical values) with zero maintenance overhead.

Token cost analysis

Both fixes eliminate error correction loops that only surface at submission time — after the full generation session has already been paid for.

Before After
SKILL.md input ~11,080 tokens ~12,264 tokens (+1,184)
Agent reasoning — find, extract, retype constants ~400–600 tokens/session ~0
Error loop — wrong resolution → reject → fix (#17) ~5,000–8,000 tokens/event ~0
Error loop — alpha rejection → diagnose → flatten → regenerate (#14) ~3,000–6,000 tokens/event ~0

Assuming 1 resolution error per 5 sessions and 1 alpha rejection per 8 sessions:

Expected savings/session = (1/5 × 6,500) + (1/8 × 4,500) − 1,184 + 500
                         ≈ 1,300 + 562 − 684
                         ≈ +1,178 tokens saved per session

The input cost pays back within a single avoided error.

Also fixes

Closes #14 — adds a dedicated Common Mistakes row for IMAGE_ALPHA_NOT_ALLOWED App Store rejections, with platform-specific fix commands (sips on macOS, ImageMagick cross-platform).

Closes #17 — eliminates the root cause of agents producing wrong resolutions, via a minimal SKILL.md change rather than a full starter project.

Test plan

  • Verify all constant values in the new block match the existing per-section values exactly
  • Confirm no existing section content was removed, only consolidated
  • Confirm Common Mistakes table includes the alpha channel row with both fix commands

…rrors

Previously, all critical numeric values (canvas dimensions, export sizes,
iPhone mockup measurements, frame ratios, width formula functions) were
scattered across several subsections of Step 5. Agents had to read,
interpret, and retype them — a non-deterministic process that silently
produced wrong resolutions or misaligned device frames.

This change consolidates every verified constant into a single
"copy this block verbatim" TypeScript block at the top of Step 5.
Agents paste it as-is; no derivation or reasoning is required.

Also adds a dedicated Common Mistakes entry for IMAGE_ALPHA_NOT_ALLOWED
rejections (source PNGs with alpha channel) with platform-specific fix
commands (sips on macOS, ImageMagick cross-platform).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Request: Add actual code to this repository bug: Generate images with transparency

1 participant