The visible feature was only the surface
README generators often preserve stale claims or produce generic sections because they do not inspect the actual project or distinguish evidence from inference.
The system also had to respect concrete constraints. The skill may edit only the root README. Features, commands, compatibility, status, URLs, metrics, and license terms cannot be invented. Applications, packages, APIs, CLIs, monorepos, datasets, and skills require different reading flows.
My role covered agent workflow design and automation engineering, with responsibility for agent workflow, validation automation, and packaging.
I turned the constraints into boundaries
Repository evidence inventory; project-type/quality references and authoring workflow; deterministic README checker plus npm installer/tests.
Treat the old README as evidence to verify, not a template to preserve.
Classify facts as verified, inferred, or unknown.
Enforce a full-document output contract rather than allowing a badge-only or single-section patch.
The key decision: Treat the old README as evidence to verify not a template to preserve.
The implementation had to prove the model
I delivered the work across the full path: Defined evidence priority and project-type routing. Bundled comprehensive quality and benchmark references. Implemented structural/content checks. Added installer, release-workflow, compatibility, and package tests.
The result is concrete: Agents can produce audience-first setup and usage docs. Preserve verified voice/attribution while removing stale claims. Surface material absences such as missing licenses. Validate that the finished README is complete.
The senior engineering lesson was that solving the visible workflow is only half the job. The architecture must also make constraints, failure modes, evidence, and ownership explicit enough for the next change to remain safe.