The portfolio that documents itself

1. Cold open

The five client case studies on this site describe work I did for others. This one describes the site you're reading.

That sounds self-obsessed. It would be, if the site were the point. It isn't — the site is a byproduct. The actual artifact is the workflow that produced it, and the workflow only holds up if I can show it working on something. This portfolio was the something.

Forty-seven memory files. Eighty journal entries. Thirteen of them promoted to durable rules. Thirty sprints across thirty-three calendar days, solo. Every decision is on disk, timestamped, in a public repo you can clone. Half the interesting ones are wrong on the first pass — the discipline is that the second pass catches them before they compound.

If you're evaluating whether AI-augmented delivery scales to a real engagement, don't read a whitepaper. Read the machine that made itself.

2. The stateless-model problem

A language model doesn't remember. Every session opens with the same blank slate: no prior context, no dated decisions, no record of which questions have already been asked and answered. Demos rarely expose this because a demo lives inside one conversation. Products don't have that luxury.

Multi-session work forces a choice. You can re-hydrate context by hand every session — quote the last decision, restate the constraint, warn about the same three dead-ends — and burn the first thirty minutes on setup. Or you can build a persistence layer around the model: durable notes the next session reads before saying anything.

Every serious agentic project ends up doing the second. The interesting question isn't whether to build persistence — it's what shape the notes take, and how you keep them from becoming a second junk drawer larger than the codebase. That's what the rest of this case study is about.

3. The persistence layer

The workflow lives in one directory: ~/.claude/projects/-Users-ruslan-portfolio/memory/. Twenty-eight Markdown files at time of writing, each with YAML frontmatter, each authored by Claude at the exact moment a durable fact crystallized mid-conversation.

MEMORY.md
brainstorm_discovery_domain_expert_agent_2026-10-03.md
case_study_template.md
feedback_auto_open_new_files.md
feedback_css_cascade_first.md
feedback_hero_content_placement.md
feedback_mdx_blockjs_false.md
feedback_prefer_written_source_over_recall.md
feedback_trust_but_verify_tooling.md
feedback_visual_direction.md
iteration-11.md
iteration-14.md
iteration-7.md
iteration-9.md
iteration-expert-v1.md
portfolio_active.md
portfolio_ai_video_pivot.md
portfolio_content_strategy.md
portfolio_design_pivot.md
portfolio_font_pivot.md
portfolio_podcast_format.md
portfolio_voice_cloning.md
portfolio_workflow.md
project_heygen_clone.md
project_video_pilot_pause_2026-09-27.md
reference_elevenlabs_video_pricing.md
reference_linkedin_api_endpoint.md
shiploop_discipline.md
user_name_romanization.md

Four types, deliberately narrow. Every entry belongs to exactly one — ad-hoc notes drift into a wiki nobody reads.

Each file has a minimum shape:

---
name: <short title>
description: <one-line hook — used at recall time to gauge relevance>
type: user | feedback | project | reference
---

The description matters more than the body. On a fresh conversation the model reads MEMORY.md — an index of one-line pointers — and only opens the files whose descriptions look load-bearing to the current task. Bad descriptions = wasted context; good ones = the machine remembering the right thing without being asked.

The featured artifact is feedback_css_cascade_first.md — one rule, one incident, one clause on how to apply it. Reproduced verbatim below.

---
name: CSS cascade before JIT/HMR blame
description: When "the same Tailwind class works on one element but not another", diagnose CSS layer/cascade first — never assume JIT ordering or HMR cache
type: feedback
---
**Rule.** When a Tailwind utility class visibly works on one element but
not another (especially: `<button>` works, `<a>` doesn't), the bug is
almost never in Tailwind's JIT compiler or Turbopack's HMR cache. It is
a CSS **cascade** problem. Look at:

1. Are there unlayered rules in `globals.css` targeting the failing
   element? (Element-level rules like `a { color: inherit }` outside
   `@layer base` beat every layered utility regardless of specificity —
   Tailwind v4 puts utilities inside `@layer utilities`.)
2. Is inheritance in play? (Anchors inherit `color` from parent by
   default; buttons don't. That asymmetry explains why the "same class"
   yields different computed values.)
3. Read the CSS bundle: `curl /_next/static/chunks/[root-of-the-server]__*.css`
   and grep for the actual rule. If the rule *is* present in the bundle
   and still doesn't win, it's cascade, not compilation.

**Why:** In the 2026-09-25 portfolio session I spent three separate
edits inline-styling CTA pills to work around what I diagnosed as a
"Tailwind JIT quirk under Turbopack HMR". The real cause was
`a { color: inherit }` sitting unlayered in `globals.css`, beating
every `.text-[color:var(--cta-ink)]` utility on every anchor CTA. The
tag difference (button vs anchor) was the diagnostic tell I ignored
three times before checking layers.

**How to apply:**
- The moment computed color/background differs from what the utility
  class prescribes AND the same class works elsewhere with a different
  tag, jump straight to inspecting `@layer` structure in `globals.css`.
- Never reach for `style={{ color: "var(--x)" }}` as a "quick fix" for
  a Tailwind class not applying — it hides a cascade bug that will
  affect other elements the same way.
- On this project the rule is documented in `STABLE_LOGIC.md` under
  "CSS authorship (Tailwind v4)"; if you break it, that file will call
  it out.

That is one file out of thirty. Every one of the others reads like this: rule at the top, incident that produced it in the middle, edge case guidance at the bottom. No lore, no essays, no aspirational principles — just what the machine needs to not repeat yesterday's mistake.

4. The MEMORY.md index

Thirty files is already too many to open blindly at the start of a session. Reading them all would eat context before the actual work started. So the memory system carries its own directory: MEMORY.md, a flat list of one-line pointers.

- [User's surname: Hrekov (not Grekov)](user_name_romanization.md) — Ukrainian romanization Г→H. Full name "Ruslan Hrekov". Gmail keeps the old spelling — do not "fix" the email.
- [ShipLoop is a discipline, not an event](shiploop_discipline.md) — classify every request; nothing gets built without spec+plan+tasks; how the user invokes ShipLoop.
- [Portfolio shiploop active](portfolio_active.md) — Sprint 0 bootstrap shipped 2026-09-20; retrofit ShipLoop discipline retroactively.
- [Portfolio workflow — wait for shiploop](portfolio_workflow.md) — superseded but kept for historical context.
- [Portfolio design pivot (2026-09-23)](portfolio_design_pivot.md) — dark Lusion → minimalist editorial. Monochrome + green dot. Reference: Nizar Ali Dribbble 24766210.
- [Visual direction — reference-first](feedback_visual_direction.md) — never write a design brief from abstract description alone; get concrete references from Ruslan first.
- [Portfolio Sprint 7 shipped](iteration-7.md) — redesign done 2026-09-23; do not reintroduce dark/three.js/gsap without new spec; copy softening held for user sign-off.
- [Portfolio font pivot (2026-09-24)](portfolio_font_pivot.md) — Playfair Display upright + strictly monochrome cursor-reactive DotGrid w/ idle breathing wave, all tunables in top-of-file CONFIG.
- [Portfolio Sprint 9 shipped](iteration-9.md) — single-page → multi-page IA. Global chrome in root layout; Nav route-based w/ prefix match.
- [CSS cascade before JIT/HMR blame](feedback_css_cascade_first.md) — same Tailwind class works on `<button>` but not `<a>`? It's `@layer` cascade, not compilation. Never inline-style-around a utility that "isn't applying".

Every line has the same shape: - [<title>](<file>) — <one-line hook>. Nothing longer, nothing hierarchical. The model reads the index in one pass, ranks which files look load-bearing to the current task, and opens only those. In practice, a typical session opens two or three files, not thirty. The index is what makes the collection scale.

5. The discipline that produces memory

Memory files don't write themselves. Something has to route each incoming message to the right pipeline: a quick question gets an answer, a bug gets a diagnose-fix-verify-log, a large feature gets a full spec+plan+tasks triple before a line of code moves. That router is ShipLoop — a nine-class classifier applied silently to every prompt (Q, B, S, L, R, T, D, M, O), each with its own model tier and its own required artifact.

Lesson: The classifier is one half of the discipline; the lifecycle is the other. Together they turn drift-prone generative work into something that compounds.

The model-routing rules (which class runs on Haiku, Sonnet, or Opus, and why) live on the About page's stack section. I won't duplicate them here; the point of the routing rules is that they're one lookup away, not restated everywhere.

6. DEVLOG → STABLE_LOGIC — the 16.3% number

Eighty entries in DEVLOG.md. Thirteen of them promoted to STABLE_LOGIC.md. That's 16.3%. The other 83.7% stayed in the journal.

Journaling and learning are not the same thing. A journal captures what happened; that's cheap and worth doing. But most of what happened is context: the shape of an incident, the sequence of dead ends, the exact error text. Useful for the next twenty minutes; noise for the next month. If every DEVLOG entry got treated as a durable lesson, the model would drown in advice — most of it about problems that don't recur.

Promotion has a bar. A rule graduates only after it holds up across at least two sessions or one full sprint. Two-session proof means the same diagnosis worked twice on different symptoms. One-sprint proof means a constraint was written into a decision and no later refactor tried to overturn it. Below that bar, the entry stays a journal note — dated, searchable, cheap to skim, but not loaded on every session.

An example. The 2026-09-25 CSS cascade incident (three edits inline-styling CTA pills, all wrong) started as a single DEVLOG entry titled "invisible CTA text." It graduated after a second session hit the same failure mode on a different element and the rule caught it in the first turn.

The two forms of the same lesson, side by side:

The DEVLOG entry is a story. The STABLE_LOGIC entry is a rule. Journaling is the raw material. Promotion is the discipline.

7. What the machine produced

Sixty-plus classified tasks. Five case studies drafted, one shipped end-to-end (Noble is the flagship), four in review. Four of the shipped surfaces, each with its own spec triple or DEVLOG entry naming what broke and what held:

The reflex says discipline slows delivery. The measurement disagrees. Every spec triple I wrote saved more time on the next session than it cost to author, because the next session started with the constraint already stated instead of re-derived from a diff. Every DEVLOG entry that graduated to STABLE_LOGIC.md prevented a class of question from recurring — the promotion is what compounds, not the journaling.

The cadence held because the failure mode of AI-assisted work isn't speed; it's drift. Same session, three different answers to the same question. Different session, the fix from yesterday reintroduced as a "clever" refactor. The memory files are what stopped that. The classifier decides which channel a request goes down; the memory decides what the model already knows before it opens its mouth. Two small primitives, one compounding result.

8. Context re-hydration saved per session

A fresh session with no memory has to be told, or has to re-derive from a diff, the exact set of decisions already made. Four of the most expensive questions, each resolved by a single file in one turn:

Rough estimate: two minutes per file × thirty files ≈ sixty minutes of ramp-up the model doesn't have to spend rebuilding context before it can act. That number is soft, but the direction isn't.

9. How to steal it

The specific memory files here are project-shaped and won't fit yours. The pattern is generalizable. Four portable primitives — each one small enough to adopt in an afternoon, strict enough that the system doesn't drift into a second junk drawer:

The actual auto-memory spec these files implement ships inside Claude Code itself. The relevant excerpt — types and when-to-save triggers — is reproduced below, attribution intact.

Types of memory. There are several discrete types of memory that
you can store in your memory system:

- user — Information about the user's role, goals, responsibilities,
  and knowledge. Great user memories help you tailor your future
  behavior to the user's preferences and perspective. Save when you
  learn any details about the user's role, preferences,
  responsibilities, or knowledge.

- feedback — Guidance the user has given you about how to approach
  work — both what to avoid and what to keep doing. Record from failure
  AND success: if you only save corrections, you will avoid past
  mistakes but drift away from approaches the user has already
  validated, and may grow overly cautious. Lead with the rule itself,
  then a Why: line (the reason the user gave — often a past incident
  or strong preference) and a How to apply: line (when/where this
  guidance kicks in). Knowing why lets you judge edge cases instead
  of blindly following the rule.

- project — Information about ongoing work, goals, initiatives, bugs,
  or incidents within the project that is not otherwise derivable
  from the code or git history. Save when you learn who is doing what,
  why, or by when. These states change relatively quickly so try to
  keep your understanding of this up to date.

- reference — Pointers to where information can be found in external
  systems. These memories allow you to remember where to look to find
  up-to-date information outside of the project directory.

What NOT to save. Code patterns, conventions, architecture, file
paths, or project structure — these can be derived by reading the
current project state. Git history, recent changes, or
who-changed-what — git log / git blame are authoritative. Debugging
solutions or fix recipes — the fix is in the code; the commit message
has the context. Anything already documented in CLAUDE.md files.
Ephemeral task details.

10. The recursive close

You're browsing the artifact.

The dot-grid canvas reacting to your cursor is Sprint 7 — a strictly monochrome cursor-only DotGrid with every tunable in a CONFIG object at the top of DotGrid.tsx, all locked in portfolio_font_pivot.md. The Playfair Display headlines are the 2026-09-24 pivot away from italic display. The route you're on (/work/hrekov-dev) exists because Sprint 9 restructured the site from single-page to multi-page. If a consent banner appeared at the bottom, you're in the EU, and Sprint 11 put it there via proxy.ts.

Every visible surface has a memory file behind it. This page is one more.