Close

Step 1: Handle the scope addition

Yasmine wants a map. Her customers get lost in the medina — the alley has no sign, and first-time visitors end up at the spice market. A map on the contact page solves that.

This is a scope addition. It was not in the original brief, not in the PRD, not in any ticket. Yasmine saw her site live and thought of something she did not think of before. This is normal. Clients see their work in the real world and realize what is missing. Scope additions are not failures of planning. They are a sign the project is alive.

You have three reasonable approaches for the map, and each involves a real trade-off:

• Embedded Google Map — interactive, zoomable, familiar to users. But it loads a third-party script, adds a dependency on Google's services, and introduces privacy implications (Google tracks visitors who interact with the embed).
• Static map image with a link — simple, fast-loading, no third-party dependency. But it is not interactive. Visitors see the location but cannot zoom or get directions without clicking through.
• Text directions with a Google Maps link — the lightest option. No images, no embeds, no dependencies. Just clear written directions and a link. But it relies on the visitor reading and following text, which is harder than looking at a map.

None of these is wrong. The embedded map is the richest experience but the heaviest dependency. The text directions are the lightest but the least visual. The static image sits in between. Pick the one that makes sense for Yasmine's visitors — people who are physically trying to find a workshop in a medina.

Whatever you choose, be specific when you direct Claude. "Add a map to the contact page" is vague — Claude will pick whatever its training data suggests, which is usually an embedded Google Map with default settings. If you want a static image with a link, say that. If you want text directions, describe what they should contain. The detail in your prompt determines whether the result matches your decision or Claude's default.

Direct Claude to implement the map addition on the contact page.

Step 2: Verify the addition

The map is on the page. But adding new content to a page that already passed verification means verifying again. The previous html-validate and Lighthouse results are no longer current — they described the page before the map existed.

Run html-validate on the contact page. AI commonly gets semantic structure wrong when adding content to an existing page — new elements may not sit correctly in the document hierarchy, or attributes may be missing. Run the tool before you trust the output.

Run Lighthouse on the contact page. If you chose the embedded Google Map, the third-party script may affect performance scores. If you chose a static image, the image size matters. AI can enumerate Lighthouse findings, but its fix suggestions tend to be generic — "optimize images," "reduce third-party impact" — rather than specific to what the audit actually flagged. Read the audit findings yourself. Understand what changed and why before directing Claude to fix anything.

The targets have not changed: html-validate 0 errors, Lighthouse >= 90 across all four categories. The addition should meet the same bar as the rest of the site.

Once everything passes, direct Claude to redeploy — same as before:

Deploy the site to Netlify with netlify deploy --prod.

Visit the new URL and confirm the map is there.

Yasmine sees the update:

Parfait! That is exactly what I needed. My cousin tried to visit last month and called me three times from the spice market. Now I can just send them the link. Merci — the site is everything I hoped for. I have already started showing it to buyers at the souk.

The project is complete from Yasmine's perspective. The site does what she asked for, and now it does one thing more.

Step 3: Write the README

Every repository needs a README. It is the first thing anyone sees when they find the project on GitHub — another developer, a potential collaborator, Yasmine's nephew who studies computer science in Lyon.

Direct Claude to create a README.md that describes:

• What the site is and who it is for
• The tech stack (static HTML/CSS, semantic markup, responsive design, Netlify)
• How to run the site locally
• The deployed URL

This is not busywork. Describing what you built and why is confirmation that you understood what you were building. If you cannot explain the project in a few paragraphs, something about the work was not clear to you. The README is the test.

Review what Claude produces. The commit convention in materials/CLAUDE.md reminds you how the project has been structured — ticket-by-ticket, each commit referencing its ticket ID. The README should reflect that same clarity.

Step 4: Push to GitHub

Commit the map addition and the README. Then push everything to GitHub.

Open the repository on GitHub and look at the commits page.

Each commit message references a ticket — T0, T1, T2, through the final additions. The history tells the story of the project: setup, structure, styling, gallery, process page, contact form, verification, deployment, and now the scope addition and documentation. Anyone reading this history can see how the work was broken down and completed piece by piece.

The commit history is not a byproduct. It is a professional artifact. It shows that the work was structured, that each piece was scoped and completed, and that the project evolved through deliberate steps rather than a single chaotic push. This is what organized work looks like from the outside.

The repository now contains everything: the HTML and CSS files, the product photos, the CLAUDE.md that governed the build, the backlog that tracked the tickets, and the README that describes the result. The deployed site is live at the Netlify URL. Yasmine is sending it to customers.

The project is done.