docs: add verbatim constants block to eliminate agent transcription errors#20
Open
eralpozcan wants to merge 1 commit intoParthJadhav:mainfrom
Open
docs: add verbatim constants block to eliminate agent transcription errors#20eralpozcan wants to merge 1 commit intoParthJadhav:mainfrom
eralpozcan wants to merge 1 commit intoParthJadhav:mainfrom
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
Assuming 1 resolution error per 5 sessions and 1 alpha rejection per 8 sessions:
The input cost pays back within a single avoided error.
Also fixes
Closes #14 — adds a dedicated Common Mistakes row for
IMAGE_ALPHA_NOT_ALLOWEDApp Store rejections, with platform-specific fix commands (sipson 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