Skip to content

W2: course v2-format consistency fix + deep audit (scaffold, canon, split, 4-persona review) - #431

Merged
pftg merged 19 commits into
masterfrom
course-w2-format-fixes
Aug 1, 2026
Merged

W2: course v2-format consistency fix + deep audit (scaffold, canon, split, 4-persona review)#431
pftg merged 19 commits into
masterfrom
course-w2-format-fixes

Conversation

@pftg

@pftg pftg commented Aug 1, 2026

Copy link
Copy Markdown
Member

W2: course v2-format consistency fix + deep audit

Second wave of the course-improvement plan (20.15). Groomed → 5 parallel scaffold-fix tasks → cross-file sweeps → full audit → 4-persona cold-eyes panel → fix round → scroll gate. Content-only (markdown + one SVG deletion + data/yaml); no templates, no CSS, no JS.

What changed (19 commits)

Grooming (re-audited against the live tree, not stale 40.22): confirmed all three defect lists, found 2 new (2.3/2.4 missing "If this fails"; C3 scope = 6 adds + 10 repositions across all 16 TL;DR lessons), struck 1 stale item (landing C1, shipped in W1).

T1-T5 scaffold fixes (parallel worktrees):

  • M1+M2 (8 files): 1.1 Success check → stranger read-aloud; 1.3 + 2.3 + 2.4 + 2.6 Success checks added; 2.3/2.4 "If this fails" blocks; outcome lines repositioned above the TL;DR; 2.5 outcome + build/pivot/kill check (Dana block untouched); 2.4 dropped its redundant tracks-mermaid (kept the funnel SVG that backs the check).
  • M4/M5 (12 files): outcome lines added/repositioned to the uniform post-badge/pre-TL;DR slot; 5.2 dropped the decorative channel-decision.svg (kept the working canvas).
  • HTCW (T4): tool roster cut 16→4 required + 1 optional expander; AI callouts demoted to prose; fake-stripe visit count aligned to the 300-visit canon.
  • hire-track split (T5): 5,558w reference split at the contract seam into hire-track (2,890w) + new fractional-cto-sow-reference (2,893w); 15 inbound links re-pointed, zero aliases; two "20 years" tenure claims → since-2011 canon.

T6 cross-file sweeps: 2 callout-rhythm walls broken; 5 shape-tell openers/closers rewritten (invented stats dropped); 7 first-mention glosses; 5 ratchet signatures.

T7 full audit (Phases 3-6): 9 fixes incl. a HIGH seam defect — the kit's DPA excerpt had dropped the customer-cancel-refund half, showing readers only the forfeit side; 3 unqualified "refundable deposit" → canon cancel-split. Canon deposit row synced to carry the split. 5.3 reveal-twist one-edit fix.

T8 4-persona cold-eyes panel (ICP-Sam / voice / AI-feel / learning-experience) → synthesized 25-item fix round → voice re-check of the worst page. Panel verdicts: assessment spine PASS (both dropped visuals were redundancy, not dual-coding loss), split routing PASS, path integrity PASS, zero pages read more AI after W2 than before. The new fractional-cto-sow-reference was the fix hotspot (relocation exposed pre-modern-gate prose: uncited numbers, unglossed MSA/SOW/CSRF); one combined numbers+gloss pass cleared it. One critic finding rejected on evidence (a canon reply-band cross-assignment).

Gates

  • bin/hugo-build green every commit (8 course validators + banned-string ratchet, new signatures pass); OKF conformant.
  • Scroll gate: desktop (1280) CLEAN on all 25 pages. SVG "failures" flagged by the walker were verified non-defects (all 3 lesson SVGs return HTTP 200, valid, correctly referenced, loading="lazy"; the walker probed a theme icon).
  • Known issue routed to W4 (NOT a W2 regression): 390px mobile horizontal overflow on 2 dense reference/kit pages — fractional-cto-sow-reference (25px, its 4-col Week/ships/ships/why-parallel teaching table) and first-paying-customer-operating-kit (51px, pre-existing since W1 W1: course landing restructure + demo-1 visual system (L3/L4/L5) #428 — W2 touched only 4 lines there). Desktop clean. The correct fix is a responsive-table overflow-x:auto treatment in course-single CSS, which is shared and campaign-window-frozen until W4; logged as a W4 input (tracker item 13). A content-side wrapper would break the tables under Hugo Goldmark.

Content-only diff → per CLAUDE.md the visual suites (test/dtest) do not apply; hugo-build + scroll gate is the contracted gate.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added a comprehensive reference on fractional CTO engagements, software-development SOWs, pricing, onboarding, acceptance terms, and production readiness.
    • Added clearer lesson outcomes, success checks, validation workflows, and troubleshooting guidance throughout the course.
  • Updates

    • Clarified pilot deposit and cancellation terms, including refund and forfeiture conditions.
    • Improved hiring, customer discovery, outreach, tracking, pricing, and MVP decision guidance.
    • Updated course links and references to improve navigation and accuracy.
    • Refined outdated claims, examples, terminology, and cost information.

pftg and others added 19 commits August 1, 2026 20:44
…k, 1.3 add Success check, 1.4 $0-path co-equal at top of budget

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… outcome above TL;DR, 2.4 drop redundant three-tracks mermaid (keep funnel SVG), 2.5 add outcome + Success check, 2.6 Success check + outcome reposition

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.1/4.3/4.4: add outcome line above the TL;DR block.
4.2/4.5: reposition existing outcome line above the TL;DR (byte-identical move).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 5.3, 5.6: add outcome line above TL;DR (Sam-voice, observable)
- 5.1, 5.4, 5.5, 5.7: reposition existing outcome line above TL;DR (byte-identical)
- 5.2: reposition + drop channel-decision.svg (decorative duplicate); keep
  channel-fit-canvas.svg as the lesson's single working visual (PDF companion,
  scoring thresholds live on it)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…isit-count canon

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…chet signatures

Two real instances: kit Built-by block and hire-track stack-section intro.
The Cagan '20 years' in reference/hire-decision-full is a distinct concept,
untouched. Ratchet entries added in the same commit per the ratchet rule.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
hire-track-supplementary-reference was 2x over the 2,900 reference cap
(5,558w). Split, moving sections whole: the Fractional CTO bridge +
Reading the SOW (the contract half, incl. production hardening checklist
and milestone-acceptance redline) move to new companion page
fractional-cto-sow-reference; find-developers, stack conversation, and
interview screen stay. Both pages now in the 1,100-2,900 band
(2,890 / 2,893 on the Phase-1 basis).

All inbound anchored links (#the-fractional-cto-bridge, #reading-the-sow,
#production-hardening-*, #the-milestone-acceptance-redline) re-pointed
across 13 course pages + 2 blog posts; link text renamed where it
literally said 'hire-track reference' but now targets the companion.
No aliases/redirects added. Sequence yaml comment lists the new
supplementary slug; page not in the linear spine, matching its parent.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2.4 had TL;DR + read-2.3-first + relates-to-2.6 as three adjacent
blockquotes; 2.5 had TL;DR + you-should-be-here-AFTER adjacent (T1 flag).
Demote the relational/prerequisite callout to a plain paragraph on each -
every fact and link preserved, standard nav-block + TL;DR untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 5.1: fabricated-precision tri-list opener ($4,200/0.4%/40-users) ->
  question-shape opener; also keeps M5 mechanism-first count at 4 (cap)
- 5.6: cinematic 'Then Week 8 lands' time-cut -> explanatory register,
  all facts kept (free-pilot enthusiasm, CFO circle-back, deposit)
- 2.3: cloned 'The instinctive first move' lead-in + invented DM stats ->
  direct-address opener
- vibe-prd-template + build-path-decision-worksheet closers: de-cloned the
  skip-X/six-weeks-later/salvage-question skeleton; the
  validated-problem-statement-template closer stays as the single
  canonical instance
- 5 ratchet signatures added for the removed phrasings
- build-path PDF regenerated (closer is in the printable body);
  untouched PDFs restored

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A gloss on page A does not cover page B - each page glosses at its own
first mention, one Sam-voice clause:
- SOC 2: hire-track ref, 4.1 decision tree, where-to-hire map
- GA4: 1.5 (back-ref to 1.3 install), 1.4 Input line, course-map table
- queues: 4.1 Q2 explainer (diagram said 'queues', body never explained
  it), 3.2 'async export queue'

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…split TL;DR (5.6 + course map + kit excerpt), Cursor seat $20-$40, M2-owned quote out of M3 walkthrough, Stripe fee capability language, first-timers generalization + 3 ratchet signatures

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… A); 5.3 reveal-twist one-edit fix (T7 F)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…+gloss+shape

- $78K story now a pointer to the SOW Reading Guide (one page owns the story)
- drop uncited 30% reply rate + 2-4-intros-in-48h claim
- link Veracode GenAI Code Security Report 2025 to source
- first-mention glosses: SOW, MSA, CSRF, RLS, pre-seed
- pattern sands: cut 50%-co-founder negative-parallelism opener, big-tech
  two-beat flip, 'Two times is enough' aphorism, names/checks aphorism,
  test-mode/production flip stated once

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…able pointer, hire-track map caption, kit FCTO/SOW trigger row

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…/DPA carry the conditions) + 5.6 CFO-scene opener

Also rides: 5.7 outcome line rewritten outcome-first (item 20) - same file
as the refundable fix. Smoke-test $1/$97 refundable charges untouched
(different mechanism).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…xpensive aphorisms, cite-tied 5.3 hook, fake-stripe flip softened

Also rides: 5.3 TL;DR de-stutter (item 25) - same file as the hook fix.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ge (2.4b/5.4/4.5), outcome lines outcome-first (2.6/4.3/1.4), Phase-1-check rename (4.4), TL;DR de-stutter (5.5-adjacent trio) + 5 ratchet signatures

Ratchet: 'In early 2026, one SaaS founder', 'is cheaper than the contract
it prevents', 'Two times is enough; one time is luck', 'Reply rate is
around 30%', 'You do not need a 50% co-founder'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… Lenny single-citation, captures verb swap

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@pftg
pftg merged commit 82deeec into master Aug 1, 2026
3 checks passed
@pftg
pftg deleted the course-w2-format-fixes branch August 1, 2026 18:46
@coderabbitai

coderabbitai Bot commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 372b8a1e-959f-4006-88ad-e92b2f1168c9

📥 Commits

Reviewing files that changed from the base of the PR and between a10c0f6 and 2b1ef2b.

⛔ Files ignored due to path filters (2)
  • content/course/tech-for-non-technical-founders-2026/build-path-decision-worksheet/build-path-decision-worksheet.pdf is excluded by !**/*.pdf
  • content/course/tech-for-non-technical-founders-2026/channel-selection-before-outbound/channel-decision.svg is excluded by !**/*.svg
📒 Files selected for processing (54)
  • .okf/content/course-canon.md
  • .okf/content/course-structure.md
  • .okf/log.md
  • content/blog/cheap-developers-expensive-without-cto-review/index.md
  • content/blog/switch-dev-shops-safely-transition-guide/index.md
  • content/course/tech-for-non-technical-founders-2026/agency-uses-ai-follow-up-questions/index.md
  • content/course/tech-for-non-technical-founders-2026/ai-token-bill-dev-shop-pass-through-cost/index.md
  • content/course/tech-for-non-technical-founders-2026/build-path-decision-worksheet/index.md
  • content/course/tech-for-non-technical-founders-2026/channel-selection-before-outbound/index.md
  • content/course/tech-for-non-technical-founders-2026/clickable-prototype-validation-2-hour-lovable/index.md
  • content/course/tech-for-non-technical-founders-2026/customers-leaving-churn-triage-not-acquisition/index.md
  • content/course/tech-for-non-technical-founders-2026/fake-stripe-pre-sale-pieter-levels/index.md
  • content/course/tech-for-non-technical-founders-2026/faq/index.md
  • content/course/tech-for-non-technical-founders-2026/find-10-people-where-to-look/index.md
  • content/course/tech-for-non-technical-founders-2026/find-10-people-with-problem-outreach-2026/index.md
  • content/course/tech-for-non-technical-founders-2026/first-paying-customer-operating-kit/index.md
  • content/course/tech-for-non-technical-founders-2026/first-ten-customers-network-list/index.md
  • content/course/tech-for-non-technical-founders-2026/first-ten-customers-outreach-message/index.md
  • content/course/tech-for-non-technical-founders-2026/first-ten-customers-send-track/index.md
  • content/course/tech-for-non-technical-founders-2026/form-your-founding-hypothesis-90-minute-sprint/index.md
  • content/course/tech-for-non-technical-founders-2026/founder-os-pack/index.md
  • content/course/tech-for-non-technical-founders-2026/fractional-cto-sow-reference/index.md
  • content/course/tech-for-non-technical-founders-2026/github-aws-database-ownership-checklist/index.md
  • content/course/tech-for-non-technical-founders-2026/hire-track-supplementary-reference/index.md
  • content/course/tech-for-non-technical-founders-2026/hiring-interview-script/index.md
  • content/course/tech-for-non-technical-founders-2026/how-this-course-works/index.md
  • content/course/tech-for-non-technical-founders-2026/module-3-walkthrough-mia/index.md
  • content/course/tech-for-non-technical-founders-2026/module-5-walkthrough-mia/index.md
  • content/course/tech-for-non-technical-founders-2026/mom-test-synthesis-build-pivot-kill/index.md
  • content/course/tech-for-non-technical-founders-2026/must-have-segment-pmf-test/index.md
  • content/course/tech-for-non-technical-founders-2026/outbound-without-sales-team/index.md
  • content/course/tech-for-non-technical-founders-2026/paid-pilot-charge-before-ship/index.md
  • content/course/tech-for-non-technical-founders-2026/pivot-or-persevere-decision-framework/index.md
  • content/course/tech-for-non-technical-founders-2026/price-hypothesis-on-smoke-test-page/index.md
  • content/course/tech-for-non-technical-founders-2026/reference/ceiling-signals-full/index.md
  • content/course/tech-for-non-technical-founders-2026/reference/hire-decision-full/index.md
  • content/course/tech-for-non-technical-founders-2026/reference/mvp-build-phases-full/index.md
  • content/course/tech-for-non-technical-founders-2026/reference/stack-tools-full/index.md
  • content/course/tech-for-non-technical-founders-2026/reference/stripe-price-test-full/index.md
  • content/course/tech-for-non-technical-founders-2026/self-serve-mvp-stack-build-phases/index.md
  • content/course/tech-for-non-technical-founders-2026/self-serve-mvp-stack-lovable-supabase-stripe-2026/index.md
  • content/course/tech-for-non-technical-founders-2026/self-serve-stack-walkthrough/index.md
  • content/course/tech-for-non-technical-founders-2026/should-you-hire-2026-decision-tree/index.md
  • content/course/tech-for-non-technical-founders-2026/slopsquatting-ai-supply-chain-attack/index.md
  • content/course/tech-for-non-technical-founders-2026/smoke-test-build-page/index.md
  • content/course/tech-for-non-technical-founders-2026/smoke-test-landing-page-7-day-demand-test/index.md
  • content/course/tech-for-non-technical-founders-2026/smoke-test-wire-tracking/index.md
  • content/course/tech-for-non-technical-founders-2026/stop-specifying-features-start-outcomes/index.md
  • content/course/tech-for-non-technical-founders-2026/validated-problem-statement-template/index.md
  • content/course/tech-for-non-technical-founders-2026/vibe-coding-ceiling-signals/index.md
  • content/course/tech-for-non-technical-founders-2026/vibe-prd-template/index.md
  • content/course/tech-for-non-technical-founders-2026/where-to-hire-developer-2026-map/index.md
  • data/course_banned_strings.yaml
  • data/course_sequence.yaml

📝 Walkthrough

Walkthrough

The course canon and lesson content now use cancellation-specific deposit rules, a dedicated Fractional CTO/SOW reference, updated cross-links, clearer learning objectives, additional completion checks, revised examples, and expanded banned-string validation.

Changes

Course canon and paid-pilot rules

Layer / File(s) Summary
Deposit terms and operating guidance
.okf/content/course-canon.md, content/course/.../paid-pilot-*, content/course/.../how-this-course-works/*
Deposit language now distinguishes founder refunds from customer forfeiture and removes blanket “refundable” wording.
Pilot agreement references
content/course/.../first-paying-customer-operating-kit/*, content/course/.../module-5-walkthrough-mia/*
The operating kit adds a 14-day full-refund rule for company cancellation, while the walkthrough specifies a non-refundable deposit.

Fractional CTO reference split

Layer / File(s) Summary
Reference split and companion content
content/course/.../hire-track-supplementary-reference/*, content/course/.../fractional-cto-sow-reference/*
Hire-track content now focuses on sourcing, stack selection, and interviews. Fractional CTO, production-hardening, onboarding, architecture reviews, and SOW acceptance guidance moved to the new companion page.
Cross-link and navigation updates
content/blog/*, content/course/.../reference/*, data/course_sequence.yaml, .okf/content/course-structure.md
Course, blog, navigation, and reference links now target the dedicated Fractional CTO/SOW page.

Lesson instruction and validation updates

Layer / File(s) Summary
Learning objectives and completion checks
content/course/tech-for-non-technical-founders-2026/*
Multiple lessons now place objectives before introductory material and add measurable success checks, failure paths, or decision thresholds.
Examples and instructional wording
content/course/tech-for-non-technical-founders-2026/*
Examples now use revised visitor counts, pricing, hiring criteria, research claims, tracking descriptions, and decision-tree language.
Regression validation
data/course_banned_strings.yaml
Banned strings now cover removed tenure claims, outdated terminology, unsupported statistics, pricing, anecdotes, and templated phrasing.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch course-w2-format-fixes

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

pftg added a commit that referenced this pull request Aug 1, 2026
…ule, split-carries-debt lesson

Co-Authored-By: Claude Fable 5 <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.

1 participant