georgewalkley.com — Implementation Plan for Claude Code

georgewalkley.com — Implementation Plan for Claude Code

Version 1.0 · 17 July 2026 · Companion to design-spec.md

This plan sequences the redevelopment into small, independently verifiable stages. Each stage ends with a local preview (bundle exec jekyll serve) reviewed by George before the next begins. Work happens on a branch (redesign), merged to the publishing branch only at the checkpoints marked MERGE. The design spec is authoritative for all visual decisions; where the two documents conflict, the spec wins.

Ground rules for the implementer

  • Never change a URL. Before starting, generate a manifest of all current URLs (from _site or the sitemap) and re-verify it after every stage; the diff must be empty apart from intentionally added pages.
  • No raw hex outside the tokens file. All colour and type decisions come from design-spec.md §4.
  • Preserve existing plugins, analytics snippets, feed, sitemap and _config.yml settings except where a stage explicitly touches them.
  • Small commits, one concern each, with messages referencing the stage number.
  • If a stage reveals something unexpected in the existing codebase (undocumented includes, plugin quirks, hand-edited HTML in posts), stop and report before working around it.

Stage 0 — Survey and housekeeping

Goal: understand the existing codebase and land the low-risk fixes.

  1. Map the repository: layouts, includes, Sass structure, plugins, data files, how posts/tags/years/pagination are generated, where analytics and meta tags live.
  2. Produce the URL manifest (ground rule 1).
  3. Fixes, each as its own commit:
    • og:locale → en_GB — done, via locale: en_GB in _config.yml (the value is generated by jekyll-seo-tag, not hardcoded in meta.html)
    • Remove maximum-scale=1.0 from the viewport meta — done
    • Diagnose and fix the /books/the-intelligence-multiplier/ redirect — diagnosed, fix deferred by George 17 July 2026. The trailing-slash URL is healthy (200, real page). The defect is on the no-slash form: redirect_from in books/the-intelligence-multiplier/index.md lists /books/the-intelligence-multiplier, so Jekyll writes books/the-intelligence-multiplier.html and GitHub Pages serves a 200 meta-refresh interstitial instead of its native 301. Every other page on the site 301s correctly. Fix is deleting that one redirect_from line.
    • Suppress or remove the zero-count “Writing” tag — cancelled 17 July 2026. George intends to populate the tag; it keeps its sidebar entry and /tags/writing/ page. Do not “fix” this later.
    • Tag vocabulary repair (not in v1.0; found during the Stage 0 survey) — done. Four posts carried tags outside the 14-tag vocabulary, two of them producing live 404s from the post template’s tag links: AI → Artificial Intelligence; Publishing Strategy → Publishing, Strategy; and two posts whose Artificial Intelligence tag used curly quotes, making it a distinct phantom tag. One post also had a curly-quoted description, which was reaching the live <meta name="description"> verbatim.
  4. Optional (George to approve before doing): add a GitHub Actions workflow building Jekyll 4.x; verify all plugins under Jekyll 4 locally before switching Pages to the Actions build.

Verify: site builds and renders identically (except the fixes); URL manifest unchanged. MERGE (housekeeping only — safe ahead of the redesign).

Stage 1 — Tokens and base stylesheet

Goal: the design system exists; nothing visible changes yet.

  1. Create the tokens layer (spec §4) as CSS custom properties.
  2. Create base styles: type scale, measure, link treatment, button/pill/card/kicker component classes, focus styles, reduced-motion guard.
  3. Load Playfair Display (weights per spec §4.2) with font-display: swap; remove any webfonts the new design does not use.
  4. Build a hidden style-reference page (/styleguide/, noindex) exercising every token and component for visual QA. Not linked from navigation.

Verify: /styleguide/ reviewed against the wireframes; existing pages unaffected.

Stage 2 — Shared includes: masthead, footer, signup card

Goal: the two elements that appear on every page, plus the reusable signup card.

  1. Masthead per spec §5, including the mobile disclosure menu and active-state logic.
  2. Footer per spec §5: signup band (Kit form, styled to tokens) + four columns. Compute total words and total weeks at build time from the post collection; retire the streak script.
  3. Signup-card include with the conditional copy logic (spec §6.5), parameterised by category.
  4. Wire both includes into the existing layouts, replacing current header/footer.

Verify: every page shows the new masthead/footer; footer stats match expectations; Kit form submits correctly (test subscription); keyboard navigation through masthead and footer works.

Stage 3 — Homepage

Goal: the curated front page (spec §6.1), replacing the blog roll.

  1. New homepage layout: hero (statement + portrait, no button), book band, recent writing (three cards, featured flag + recency logic), services, footer.
  2. Move the blog roll’s job to /posts/ — until Stage 4 restyles it, the existing listing continues to serve there so nothing breaks.
  3. Placeholder-tolerant: build with the real portrait and cover if supplied, otherwise neutral placeholders sized per the wireframe.

Verify: desktop and 360px mobile against wireframe v3; hero stacks correctly; card population logic tested with and without featured flags.

Stage 4 — Archive template

Goal: /posts/, tag pages and year pages (spec §6.4).

  1. Compact list entries; filter pills on the category field; retained pagination.
  2. Sidebar with untruncated topics and years; stacks below the list on mobile.
  3. Tag and year pages restyled onto the same template at existing URLs.

Verify: pagination URLs unchanged; pills filter correctly once categories exist (temporarily, uncategorised posts appear under All only); a long tag list sits acceptably beside a short page.

Stage 5 — Post template

Goal: the reading experience (spec §6.5).

  1. Single-column layout at 65–70ch; metadata line with build-time reading time; typography, blockquotes, image treatment per spec.
  2. Tag links, category-aware prev/next with global fallback, conditional signup card.
  3. Spot-check rendering across a sample of old posts (earliest years, posts with images, posts with unusual markup) — legacy content must not break.

Verify: reading view on desktop and mobile; prev/next logic across category boundaries; signup copy correct for both categories.

Stage 6 — Book page and static landing pages

Goal: spec §6.2 and §6.3.

  1. Book page: hero with retailer buttons (data-driven), endorsement pattern from _data/endorsements.yml (lead + grid, 2–8 entries), demoted inside-the-book prose, launch-updates card with its Kit tag.
  2. Static landing template applied to Consulting, Speaking, Training, Newsletter, About with per-page fills. Existing page content is restructured into the new sections with George’s review — content edits are proposals, not silent rewrites.

Verify: each page against spec; endorsement grid tested at 1 lead + 1, + 3 and + 7 entries; retailer buttons wrap correctly on mobile. MERGE candidate: stages 1–6 can go live together once George approves the full preview.

Stage 7 — Content categorisation pass

Goal: every post carries a category (spec §7).

  1. Script or agentic pass over _posts/: propose newsletter or post per file, inferred from tags, title pattern (Context Window issues) and content.
  2. Output as a reviewable diff (or a proposal table: filename → proposed category → evidence) for George’s approval before any front matter is written.
  3. Apply approved values; add description: lines opportunistically where an obvious one-line summary exists (also as reviewable proposals).

Verify: archive pills now partition the full archive; no post uncategorised; homepage cards label correctly.

Stage 8 — QA and launch

  1. Full-site pass: URL manifest diff empty; feed and sitemap valid; analytics firing; OG/Twitter meta correct per page.
  2. Accessibility: keyboard-only walkthrough, focus visibility, landmark structure, alt text, pinch-zoom.
  3. Lighthouse on homepage, one post, archive, book page — performance and accessibility both ≥ 90; fix regressions (typical culprits: font loading, unoptimised portrait/cover images — serve appropriately sized, compressed assets).
  4. Cross-check Kit submissions from every placement land with the right tags.
  5. MERGE to publishing branch; confirm live site; update og-default.png when the refreshed asset exists.

Post-launch (December 2026)

  • Flip the book kicker config to out-now; add/adjust retailer links.
  • Review newsletter signup rates by placement (Kit tags); reinstate a hero button only if the data argues for it.
  • Consider adding an Events/Engagements strip to the Speaking page from the autumn schedule.

Inputs needed from George (blockers by stage)

Stage Needed
0 Repository access; approval for the Actions/Jekyll 4 move
2 Kit form/tag IDs per placement; confirmed subscriber-count wording
3 Portrait and cover assets; final hero copy
6 Retailer URLs; endorsement copy; landing-page content review
7 Approval of the categorisation diff; “Posts” vs “Articles” confirmation