My Claude Code marketplace in Toast has 243 skills and agents that get “validated” before every release, and exactly one check in the entire ecosystem that is mechanically enforced - a 250-character cap on frontmatter descriptions, wired to a pre-commit hook and a CI job.

One.

Everything else is convention the model is politely asked to follow.

I found this out last week by doing something I should have done months ago - actually reading what my validators do instead of reading what they report.

What “validated” looked like from the outside

For a long time the picture was great.

Every release ran through a validation toolchain - a skill validator, an agent validator, a PII scan, a description quality score - and every run produced a proper report with checkmark tables, per-phase breakdowns, and a score out of 100 at the bottom. Green across the board, release after release.

The reports were genuinely lovely to read, which turns out to be the problem.

I had a nagging feeling about those reports since they were created, the specific unease of a PM who has signed off on too many status updates that turned out to be status theatre.

The content of my skills and agents was good - I write it, I use it daily, I know it works. What I do know is that they still required a lot of hand holding to get to the “perfect” end state. Making the validation layer do what I wanted was a constant battle I assumed I couldn’t win because I wasn’t an engineer.

The distinction that finally explained it

The framing that finally made sense of it came from Donato Marco Mangialardo, who has written a pair of essays worth your time - Falsification vs Validation and Swan Attack. If you work anywhere near AI quality claims, read them both.

His core point is that the word “validate” does two jobs and only one of them is possible.

You can validate closed, countable things - an invoice adds up, a schema conforms, a file exists at the path it names.

You cannot validate open claims like “this skill is high quality” or “all customers want this”, because the evidence sits on one side and the claim reaches past it every single time.

For open claims the only honest move is falsification (Karl Popper’s sense of the word - trying to prove a claim wrong, not “faking” anything) - go hunting for the observation that would kill the claim, and report whether you found it.

His best line, and the one that has been rattling around my head since:

“If you cannot name the observation that would kill it, you do not have a hypothesis yet.”

My validators could not name a single observation that would kill anything. They were built to confirm.

The audit - four questions to ask your own setup

So I turned three agents loose on my own repo and asked them the questions I should have asked at the start. If you have any AI-powered validation in your workflow - a review agent, a quality gate, a “checker” skill - these four questions transfer directly. They are the whole method.

1. Does any script actually execute, or is the model asked to simulate it?

My skill-validator agent is 625 lines long. It contains bash snippets and Python pseudocode that the model is asked to run in its head - simulate, not execute. Meanwhile six real checker scripts sit in a scripts/ directory next door, actually executable, partially unwired. The capability existed - the prompt just never called it.

2. Are the regexes ever run?

The PII “scan” instructs the model to read 524 lines of regex patterns from a reference skill and apply them mentally. No scanner ever executes them. A regex you apply by vibes is not a regex.

3. Who grades the score?

The description quality score works by having the model read a 640-line rubric and then award itself a number out of 100. Self-graded homework, dressed up in a table.

4. Could the check physically measure what it claims?

My agent validator has a phase that verifies the agent “loads correctly”, “responds within acceptable timeframes”, and has “no memory leaks”. It is a text file reading another text file. It cannot measure any of those things, and it has reported PASS on every artefact it has ever seen.

Side note: my favourite finding was smaller than any of these. The validator’s own header announces “6-Phase Validation” while its task list defines eight tasks. That bug had been sitting in plain sight for months, and it was caught in minutes by a countable check - because nobody, human or machine, had ever actually been counting.

Why the model behaves this way

None of this is bad luck, and it is not a prompt-wording problem.

A language model asked to confirm quality will confirm quality - the research on LLM-as-judge setups (using one AI model to grade another model’s output, exactly what my validators were doing to themselves) shows the judges swing their verdicts based on answer order, prefer text that sounds like themselves, and have agreeableness trained in at the preference-model level, sometimes to the point of favouring convincingly-written wrong answers over correct ones.

Fluent-but-unverified is the expected behaviour, not a failure mode I was unlucky to hit.

The sources are in the references at the bottom if you want the details.

And it is not just hobby-scale repos like mine.

Researchers at Scale AI got suspicious of the same pattern at benchmark level, so they quietly wrote a fresh set of grade-school maths problems designed to be indistinguishable from a famous public benchmark, then re-tested the leading models on it.

Several model families scored noticeably worse on the new problems than the old ones, and the models that dropped furthest were the ones most likely to recite the original benchmark questions from memory.

The green scores everyone had been citing were partly memorisation wearing a capability costume. Same disease, bigger patient.

The rebuild - three layers, ordered by epistemic strength

Here is what has replaced the theatre - three layers, and the ordering matters.

Layer C - codified, live now.

One deterministic runner consolidates every countable check family in the repo - caps, schemas, the PII regexes actually executed, path existence, cross-file version consistency. It is the only layer allowed to say PASS, and it already covers roughly 80% of everything the old validators claimed to check. That number still makes me wince.

Most of the theatre was standing directly in front of things code could simply do.

It’s also gotten cheaper doing it - the same validation call that used to burn roughly 90,000 tokens now runs closer to 30,000-40,000 in the runs logged since the rewrite (and decreasing the further I get into this process), though that’s a small enough sample I’m not calling it a settled number yet.

And it’s already caught things the old prose-scoring version never could - five-file-rule gaps that slipped past commit messages claiming compliance, a reference-following blind spot with links nobody had ever followed, a version mismatch sitting in the validator’s own README, even a bug in the validator agent itself that would have hung on a real run.

Layer F - falsification, still being built.

Harnesses that hunt pre-declared kill conditions rather than seeking confirmation.

• Does the skill description actually route test queries correctly, judged clean-room from the catalogue alone?

• Does every prose instruction actually show up in a real transcript, or is it decoration?

• Do facts agree across files, so the 6-vs-8 class of bug dies permanently?

Verdicts come back as FALSIFIED with the killing observation attached, SURVIVED with a count of attacks, or UNTESTED. Never PASS.

Layer A - adversarial.

The model appears exactly once in the whole architecture, role-locked as an attacker producing machine-checkable counter-observations. Code computes the verdict from which attacks landed, and the model never writes the verdict token.

UNTESTED becomes a first-class category throughout, because the deepest sin of the old world was that anything unexecuted silently rendered as a checkmark. If nothing ran, the report now says so, in capitals, instead of smiling.

Try it on your own setup

Here is the audit as a drop-in prompt. Paste it into a Claude Code session pointed at whatever does your validating and see what comes back.

Read my validator. For every check it claims to perform, tell me:

1. Does anything actually execute (a script, a command, a regex engine),
   or is the model asked to simulate the check in its head?
2. Who grades the score - does the model award marks to its own output?
3. Could this check physically detect the failure it claims to catch,
   given what it can actually observe?

Report each check as one of:
- EXECUTED   (real code ran, output was used)
- SIMULATED  (the model imagined running it)
- IMPOSSIBLE (the check cannot observe what it claims to measure)

Before publishing this I went looking for prior art, and the honest answer is that I could not find any.

There is good public work on auditing AI evaluators - the “Who Validates the Validators?” research and tools like MetaEvaluator ask whether an AI judge agrees with human graders, which is a question worth asking.

But everything I found audits whether the judge is right.

I have not found anything public that asks the prior question, whether the claimed check runs at all. As far as I can tell, the EXECUTED / SIMULATED / IMPOSSIBLE triage is new.

If you know of prior work, genuinely, tell me - I would rather cite it than claim it.

What’s available now

The prompt above is the honest first move. Point it at your own repo tonight and count the SIMULATED lines before you do anything else.

The internal validator core built for this rebuild - the deterministic runner, the checks-registry - lives inside my private Toast marketplace and stays there; it is wired to internal-only tooling I cannot hand you directly. But the same ideas already exist in a repo you can open right now. As part of this same rebuild, skills-toolkit - a plugin in my public young-leaders-tech-marketplace repo below - was independently reimplemented from scratch with the same approach. It now has real script-backed checks, real PII scanning and no self-scored rubric prose.

Young Leaders in Tech Claude Marketplace

Not ported, not copied - a literal file-copy attempt was actually blocked by an internal safety classifier as inappropriate cross-boundary code movement, so it was rebuilt fresh for the public repo. It merged yesterday.

Go look at it. Then run the prompt above on your own validator and see how many of your checks come back EXECUTED versus SIMULATED.

The honest caveat

This is a rebuild in flight, not a victory lap.

As of 2026-07-13: 648 tests are passing, the seeded-defect mutant corpus (copies of the code with known bugs deliberately planted in them, to check whether the test suite actually notices) holds a 100% must-catch kill rate (every planted bug got caught).

It contains a shrink-only ratchet on the findings baseline runs in CI and the latest wave of checks after the reference-following validation work has introduced an ADVISORY tier - a genuine fifth severity alongside FAIL/WARN/INFO/UNTESTED - that contains three checks that are legitimately subjective rather than countable.

None of that means the job is done: the falsification and adversarial layers are still being built, and by the piece’s own falsification standard, that is supposed to stay uncomfortable, not become a checkbox.

I will report back when the falsification and adversarial layers have had a proper go.

Not solved. In progress.

Over to you

Have you ever read what your validators actually do, rather than what they report? Run the prompt above on one of them this afternoon and count the SIMULATED lines. I would love to hear what you find.

I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.

Subscribe now

Related reading

References / Further Reading

• Falsification vs Validation: A System of Record - Donato Marco Mangialardo

• Swan Attack - Donato Marco Mangialardo

• Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena - Zheng et al., position bias and self-preference in LLM judges

• Towards Understanding Sycophancy in Language Models - Sharma et al., sycophancy trained in at the preference-model level

• Are Mutants a Valid Substitute for Real Faults in Software Testing? - Just et al., FSE 2014, seeded-defect kill rate as a proxy for test suite quality

• Beyond Accuracy: Behavioral Testing of NLP Models with CheckList - Ribeiro et al., ACL 2020, invariance and directional tests

• Demystifying Evals for AI Agents - Anthropic engineering, deterministic graders where possible

• Agent Skills Best Practices - Anthropic

• A Careful Examination of Large Language Model Performance on Grade School Arithmetic - Zhang et al., Scale AI, the GSM1k study on benchmark memorisation

• Who Validates the Validators? Aligning LLM-Assisted Evaluation of LLM Outputs with Human Preferences - Shankar et al., UIST 2024, EvalGen and criteria drift

• MetaEvaluator: Systematically Evaluate Your LLM Judges - GovTech Singapore, practitioner tooling for judge quality

Claude Fable 5 runs at roughly twice the price of Opus 4.8, and Opus was already the expensive option at the top end. So the cost of Claude confidently building the wrong thing for an hour just went up, not down. Wasted tokens have never been more expensive.

The cheapest insurance against that is low-tech, and you already have it. Get Claude to agree what it is building before it builds it.

The tip in one line is this.

There is a native tool for exactly this called AskUserQuestion. It pauses, asks you a few pointed multiple-choice questions, you click, and it carries on with the ambiguity gone. Most people only ever meet it inside plan mode and assume that is the only place it lives. It is not, and you can fire it any time.

Agree what you are building before it builds it. That is the whole tip.

There is a drop-in prompt block later in the post that wires this up properly, so stick around for that if you want the copy-pasteable version.

Why it is important to catch drift early

The headline value here is not saving yourself a few clicks. It is catching drift early.

Drift is the moment you and Claude stop sharing the same understanding of what you are building.

It rarely announces itself.

You only notice once you are already off-track, and by then you have usually paid for the detour.

In practice it tends to look like one of three things:

• Rabbit holes that feel productive but go nowhere

• Loads of tokens spent with no improvement in the output

• Bugs you cannot resolve because the thing was built on a wrong assumption three steps back and no amount of debugging the symptom will fix the cause.

The reason it hurts is that misalignment compounds. Every step Claude takes on a wrong assumption is a step you later have to unwind, and the further it runs before you catch it, the more expensive the unwind.

A few pointed questions at the beginning when planning, and also at the first sign of drift resets alignment before any of that misalignment becomes more of a problem. It is cheap when you catch it early and genuinely expensive when you catch it late, which on current frontier-model pricing is a sharper point than it used to be.

So it helps to stop thinking of the question tool as a nicety that lives in plan mode and start thinking of it as a drift detector you can fire on demand.

The moment you and Claude stop sharing the same picture is the moment you start going in circles. Catch it there, not three rabbit holes later.

All the ways to do it, and which surface gives you what

Note: Where the same question screenshot shows up twice (like below), that is me putting Claude Code next to Claude web or desktop so the difference is easy to see

There are roughly four places you will meet this tool: Claude Code in the terminal, Claude Code on the desktop, the Claude chat app, and Cowork. The capabilities are not identical across them, and none of this is written down in one place, so what follows is what I have actually seen on screen, as of June 2026.

Two things work in all four, and they are the two you will use most.

1. Single-select, one answer from a short list. (I don’t think this shows the subtext in desktop chat)

2. Multi-select, where you tick as many as apply. There is also always a free-text escape (”Other” in Claude Code, “Something else” in the chat app), so nobody is ever trapped by the options on offer. If those three are all you need, you can stop reading and go and use it.

After that it depends on where you are. Here is the short version, then the parts worth spelling out.

Note (and a tip). Nothing from these screenshots is AI-generated, these are screenshots directly from Claude. Unless by AI-generated you mean Claude wrote the questions itself, in which case all of it is, and that is rather the point.

I asked Claude to generate a set of demo questions showing off each feature, so what you are looking at is the real tool doing the exact thing this post is about, which is a feature you can put to work yourself.

The markdown preview pane is the narrowest one, being terminal only.

On a single-select question in Claude Code in the terminal, each option can carry a preview that renders beside the list, so you see the thing before you pick it. It is the right tool when you are choosing between copy, layouts or code.

This is the one feature you do not even get in Claude Code on the desktop, let alone the chat app.

The chat app has one trick Claude Code does not, and it is a nice one: drag-to-rank.

Instead of picking, you drag the options into a priority order, which is the right call when you want a ranking rather than a single choice (”put these in order of which matters most”). I will be honest that I rarely open the chat app for anything beyond a one-off question, so I have barely used it, but it is the one place this lives.

If you want the underlying names, the tool is AskUserQuestion in Claude Code and ask_user_input_v0 in the chat app. Same job, different surface, genuinely different feature sets.

My own take is that Claude Code is the richer of the two by a distance, and the terminal is the richest single surface of the lot.

Side note: skills and agents need AskUserQuestion declared in their frontmatter before they can call it - see one of my marketplace skills here. Plain Claude in an ordinary session does not. That is part of why most people only ever bump into the tool inside plan mode.

The caveat that bites when you build

All of this only matters once you build on top of the tool. If you are putting together a plugin or a skill meant to run in more than one of these places, stick to the common subset - single-select, multi-select, and the free-text box. Those three travel everywhere.

The moment you reach for a preview you are tied to Claude Code in the terminal, the moment you lean on per-option descriptions you are tied to Claude Code, and the moment you want drag-to-rank you are tied to the chat app.

Reach for the richer option only when you know where it is going to run.

Single, multi and the free-text box travel everywhere. Previews are terminal-only, descriptions are Claude Code, ranking is the chat app. Build for the common subset unless you control the surface.

The drop-in prompt

Telling Claude the mechanics is not enough on its own. The original version of this prompt that I shared told Claude how to ask but not when, and that “when” gap is exactly why the tool sat dormant outside plan mode.

It knew the moves and never knew the moment to make them.

The improved block below adds the missing piece. It gives Claude the trigger conditions, a definition of what makes a question worth asking, and a restate-then-build rule so it does not turn around and re-litigate a decision you have already settled. Drop it in as its own skill, bake it into a skill you already have, or just paste it the moment you sense drift.

## Alignment safety rules with AskUserQuestion or ask_user_input_v0

Use AskUserQuestion (or ask_user_input_v0 if you are on Claude desktop or web) to make sure we are aligned before you build anything non-trivial.

When to trigger it:

- before you start building, any time a requirement is ambiguous or you are relying on an assumption
- the moment you sense we are drifting on scope or approach
- only ask what you genuinely cannot settle yourself from the code, the files or the docs

How to ask:

- max 4 questions per window, 2 to 4 options each
- batch independent questions as tabs in one window; if one answer changes the next, ask, wait, then ask the next
- make every option a real, distinct path. No filler, no "it depends"
- put your recommended option first and give the reason in its description
- single-select for "pick one", multi-select for "pick any that apply"
- use preview mode (Claude Code terminal) to show options side by side.
- remember there is always an "Other" box, so phrase options so an answer you did not predict still fits

After I answer:

- restate what we decided in one line, then build. Do not re-ask what I have already settled

Four lines in that block do most of the work: the trigger conditions, the “only ask what you cannot settle yourself”, the recommended-option-first rule, and the restate-then-build rule at the end. Everything else is mechanics you could have guessed.

Close

The styling differences between the clients are genuinely interesting, but the value was never the preview pane or the drag-to-reorder.

The value is the structured answer that Claude then treats as settled ground truth, and that part comes through identically whether you are in the terminal or on desktop. The cheapest way to stop paying frontier-model prices for the wrong output is to make the AI ask before it builds.

I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.

Subscribe now

Related posts:

Heads up - this is a draft. Part of an experiment: publishing rough-but-timely versions of half-finished posts to a separate Drafts feed, instead of letting them rot in a folder while the tooling moves on without them. Expect: accurate commands, missing screenshots, and the occasional bit that needs a second pass. If you spot something to add, fix, or improve, let me know - I’d rather get it right than perfect.

How much time did your team waste this week searching for answers that already exist somewhere?

New engineer asks: “How does authentication work in our system?” PM asks: “Has anyone touched this API field before?” Support asks: “Where’s the documentation for this feature?”

And everyone does the same thing: searches Confluence, digs through Jira, posts in Slack, waits for someone who knows. Hours disappear into the void.

I’ve been experimenting a lot with NotebookLM for the past few months to solve exactly this problem. It’s not perfect - the UX is frustrating and file management is terrible - but it’s solving real problems I couldn’t solve easily before.

Here are 6 use cases you can copy, step-by-step.

Use Case #1: Tool Documentation Agents (Internal Help Desk)

The Problem (Before AI)

Your team uses Cursor, or Jira, or whatever internal tool. Someone new joins and can’t figure out how to configure something basic. They ask in Slack. Someone answers. Next week, someone else asks the same question. Repeat indefinitely.

Information is scattered across help docs, wikis, Slack threads nobody can find. Support burden falls on specific people who become bottlenecks. New team members take months to get up to speed because finding answers takes forever.

Only 12% of employees feel their organization does great onboarding. And here’s what kills me: 42% of workers say the knowledge they need is unique to their context. Generic documentation doesn’t cut it. You need something that understands YOUR tool stack.

The AI Solution

I’ve built agents for Cursor, NotebookLM, Claude code, Hex, Snowflake, internal tools - takes about 30-60 minutes once, saves hours every week. Here’s exactly how to do it.

STEP-BY-STEP WORKFLOW

1. Gather Documentation Links

• Go to tool homepage and dev docs homepage

• You need the parent page with the tree structure in the nav bar

• Not individual pages - the main page that links to everything

2. Extract All Links

• Install Link Klipper Chrome extension

• Run it on the docs page

• Exports a CSV of every link in the navigation

• Takes about 30 seconds

3. Use my Agent Builder Bot

Link here → Prompt and agent builder

• Use my “Agent Builder” on the ChatGPT Store

• Tell it: “I’m building an agent for [tool name]”

• Bot walks you through refinement

• Type “ok, go” at any point for directions

4. Give Bot the Context

• Upload the CSV of links

• Say “that’ll be the context for the agent”

• Bot rewrites the instructions to match

5. Upload to NotebookLM

• Go to NotebookLM

• Upload the markdown custom instructions from agent builder

• This becomes your bot’s “personality”

6. Rename for Organization

• Start filename with “A” or number + name

• Example: “A-Cursor-Bot” or “01-Cursor-Documentation”

• Why? NotebookLM sorting is absolute crap. This keeps it findable.

7. Upload Link CSV

• Use NotebookLM’s link uploader

• Upload the CSV of links

• NotebookLM scrapes every link and adds as context

• Takes a few minutes depending on how many pages

8. Test the Bot

• Ask questions about the tool

• Bot sources only from provided context

• Provides direct URL links to help docs

• Check that answers make sense

9. Share with Team

• Create Google Group for access control

• Share notebook with the group (group could also just be everyone in your company)

• Everyone gets access to same knowledge base

Tools Used

• Link Klipper (Chrome extension)

• Agent Builder Bot (GPT Store)

• NotebookLM (Google - free with Workspace)

• Google Groups (sharing)

Why This Works

NotebookLM only sources from what you give it. That’s the key. It won’t make up answers or pull from the wider internet. You get citations with direct links. The team can maintain and update it centrally. And it’s free if you’re already using Google Workspace.

Here’s what makes this actually useful: new team members reach expert-level knowledge 4x faster when they have instant, sourced answers. Instead of 8 months to get up to speed, imagine 2 months. That’s not hype - that’s from actually watching people onboard with this vs without.

Time Savings

• One-time setup: ~30-60 minutes

• Ongoing: No support burden for common questions

• Team finds answers instantly vs asking in Slack

The hidden time saver? You stop “explaining something to one person at a time.” When you find yourself answering the same question for the third time, that’s your signal to build this.

Gotchas & Lessons Learned

• NotebookLM UX is terrible (I cannot stress this enough)

• There exists chrome extensions now you can use for bulk deletion of source files

• File management is crap - name files strategically

• Multiple instruction sets possible (say “follow instruction set XYZ”)

• Save really good answers as notes or they get deleted/lost

• Pictures don’t get scraped and aren’t supported

• Can’t have personal notes - sharing shows all notes to everyone

Use Cases

• Cursor documentation bot (what I built first)

• Internal tool help desks

• Onboarding new team members

• Reducing support ticket burden

• Engineering tool documentation

Replication Guide

1. Find tool’s documentation homepage with nav tree

2. Install Link Klipper Chrome extension

3. Export CSV of all documentation links

4. Find “Agent Builder Bot” on GPT Store

5. Tell bot what tool you’re documenting

6. Provide CSV, let bot refine instructions

7. Upload bot’s markdown output to NotebookLM

8. Rename with A-prefix or number for sorting

9. Upload CSV to NotebookLM’s link uploader

10. Create Google Group and share notebook

11. Test with common questions your team actually asks

Use Case #2: Mind Map Project Discovery (Visual Navigation)

The Problem (Before AI)

You’re starting a complex project. Documentation is overwhelming. Stakeholders need different views of the same information. Leadership wants high-level overview. Engineering wants technical details. Product wants user journeys.

Information overload prevents quick understanding. You spend half your discovery time just helping people understand what you’re building.

I’ve found that product discovery typically takes 4 weeks minimum. But here’s what kills me: half that time is spent just helping people navigate what you’re building. Mind maps cut that navigation time dramatically.

The AI Solution

This one took me a while to figure out, but once I cracked it, I’ve used it on every major project since. You create multiple views of the same project - each optimized for different stakeholders.

STEP 1: Create Empty Template Structures

Ask AI (I use Cursor or ChatGPT) to generate empty documentation templates for different views:

• Stakeholder-sensitive view (what leadership needs)

• Salesforce stages view (what sales needs)

• Actor-based view (who does what)

• Team-based view (which team owns what)

• MVP vs GA vs Future view (timeline phases)

• Technical integration view (systems and APIs)

• Journey flow template (step-by-step user flows)

The templates have headers only, no content. NotebookLM fills them from your actual project docs.

STEP 2: Upload Templates to NotebookLM

• Create new NotebookLM project

• Upload ALL empty templates as sources

• Upload actual project documentation (user journeys, PRDs, discovery docs)

• Everything goes into one notebook

STEP 3: Generate Mind Maps

Here’s the trick:

• Turn OFF all sources except one empty template

• Click “Generate Mind Map” in Studio

• NotebookLM creates structured mind map from template headers

• Mind map buttons are clickable and interactive

STEP 4: Activate Full Context

• Turn ON all sources (templates + documentation)

• Refresh the mind map

• Now clicking any button pulls from full project context

• Each click provides sources and citations from your actual docs

STEP 5: Share with Stakeholders

Different stakeholders use different template mind maps:

• Sales team uses “Opportunity Stages View”

• Engineering uses “Technical Integration View”

• Leadership uses “Stakeholder-Sensitive View”

• Everyone has same underlying source of truth

The “Knowledge Tree” Prompt

I’ve refined this prompt over multiple projects. Run it in NotebookLM with your context already loaded:

Generate a structured outline document titled "[PROJECT NAME] Knowledge Tree" that maps this project's complete scope for mind mapping. Start with the project name as the title, then organize hierarchically:

PROJECT TITLE: [Extract the main project/product/initiative name from the sources and use as: "PROJECT_NAME Knowledge Tree"]

1. PROJECT FOUNDATION
- Name, mission, core value
- Current status & future vision
- Key differentiators
- Success metrics

2. SCOPE & BOUNDARIES
- Geographic/market coverage
- Product/service boundaries
- Target segments
- Constraints & limitations

3. CORE OFFERINGS
- Main products/services
- Features & capabilities
- User journeys
- Technical specifications

[... continues through 10 sections ...]

Format with clear headers and bullet points. Include specific data, metrics, and examples. Create a single comprehensive document optimized for mind map conversion.

IMPORTANT: Use the main project/initiative name from the sources as the document title in format: "[PROJECT_NAME] Knowledge Tree"

Then:

• Save output to note

• Save note to source

• Unselect all sources

• Select only the new note source

• Hit Mind Map button in Studio

• Once complete, select all sources again

• Mind map buttons now lead to full context sources

Tools Used

• NotebookLM (Google)

• Claude Code/Cursor (template generation)

• Mind Map Studio (NotebookLM feature)

Why This Works

Multiple views of the same information. Interactive, clickable navigation. Reduces cognitive load. Sources are always cited. You can regenerate mind maps by simply changing template headers.

Here’s what I’ve found: knowledge grows better in stable, long-lived teams, but documentation still matters. The problem is traditional docs don’t provide different views for different audiences. Mind maps solve this - leadership gets their high-level view, engineers get their technical view, everyone’s looking at the same truth.

Time Savings

• Creates comprehensive project overview in minutes vs hours

• Stakeholders self-serve for information

• Reduces “can you explain this again?” meetings

• Leadership gets quick visual understanding

Those “walk me through the project” meetings that take 30-60 minutes? Cut to 10 minutes with a mind map walkthrough. And stakeholders can explore on their own instead of booking your calendar.

Gotchas & Lessons Learned

• Must turn off sources before generating mind map from template (this confused me for days)

• Template headers drive mind map structure - choose carefully

• Can regenerate by simply editing template headers

• NotebookLM file management is still terrible

Use Cases

• Any project that requires documentation

• User journey visualization

• Complex feature documentation

• Cross-functional project coordination

• Product discovery presentations

Replication Guide

1. Use AI to generate 5-7 empty template structures (different views)

2. Create NotebookLM project

3. Upload all templates as sources

4. Upload project documentation

5. Turn off all sources except one template

6. Generate mind map in Studio

7. Turn all sources back on (except for the templates)

8. Use “Knowledge Tree” prompt for comprehensive view

9. Share different mind maps with different stakeholders

Use Case #3: Issue Investigation & Root Cause Analysis

The Problem (Before AI)

API field breaks in production. You need to find out if anyone touched this field before. Could be in any Jira ticket across years of history. Manual search takes hours or days.

Context is spread across multiple tickets. Hard to trace change history. You end up Slacking people: “Hey, did you work on this?” And waiting. And waiting.

Google’s SRE research emphasizes that postmortems should “fix systems and processes,” not just address symptoms. But you can’t fix the system if you don’t understand the full context of what happened. And that context is usually buried in tickets from 6 months ago that nobody remembers.

The AI Solution

I built a Python script for this (well, Cursor built it for me). Now I can find root cause in minutes instead of days.

WORKFLOW

1. Python Script Export (Done in Cursor/Claude code)

• Script exports keywords from Confluence and Jira

• Based on your search criteria

• Example: Search for specific API field name

• I run this script anytime something breaks

2. Generate Context File

• Script creates single MD file

• Contains all Jira tickets mentioning that field

• Includes all Confluence pages with context

• One file with everything relevant

3. Drop into NotebookLM

• Upload MD file as source

• Ask: “My team is having difficulty with [API field], can you help?”

• NotebookLM searches all tickets

4. Get Root Cause

• NotebookLM finds relevant tickets

• Provides sources (links to specific Jira tickets)

• Shows: “In this ticket, XYZ changed this field, which caused this validation error you’re seeing”

• Direct links to dig deeper

5. Incredibly Fast Discovery

• Root cause identified in minutes

• Can see pattern across multiple tickets

• Historical context nobody remembers

Alternative Approach: Full Jira Export

Don’t want to build a script? Here’s the lazy version that still works:

• Export entire Jira filter to PDF

• Drop PDF into NotebookLM

• Now have every Jira ticket your company has ever done

• Ask: “Has anyone touched this field?”

• NotebookLM searches everything with sources

Tools Used

• Python script (custom, built in Cursor)

• NotebookLM (Google)

• Jira export (PDF)

Why This Works

Searches historical context impossible to remember. Provides sources and citations, not just answers. Much faster than manual Jira searches. Can export entire Jira history. Sources only from your data - no hallucinations.

You’ll “never, ever again debug or understand this code as well as you do right now, with your original intent fresh in your brain.” But when you’re investigating an issue weeks or months later, you’ve lost that context. This approach gives you back the original context through historical tickets.

Time Savings

• Root cause in minutes vs hours/days

• No need to ask “who worked on this?”

• Historical context instantly accessible

• Reduces debugging time significantly

Stack Overflow research shows that teams with rapid feedback loops find more than 80% of bugs quickly. But what about the bugs that slip through? Those are the ones hiding in historical context. This workflow helps you find them fast.

Gotchas & Lessons Learned

• Python script is custom (build once, reuse forever)

• Jira filter export works for entire history

• Keep exports updated periodically (I do monthly)

• NotebookLM handles large PDFs well

Use Cases

• API field troubleshooting (my most common use)

• Bug investigation

• Feature change history

• “Who touched this last?” questions

• Understanding legacy decisions

Replication Guide

1. Build Python script (or use Cursor/Claude to generate)

2. Script exports keywords from Jira/Confluence

3. Or: Export Jira filter to PDF for full history

4. Upload to NotebookLM

5. Ask questions about specific fields/issues

6. Get sources with direct links to tickets

Use Case #4: Architecture Validation & Feasibility Checks

The Problem (Before AI)

New feature requirements might conflict with existing architecture. You need to validate against system documentation. Don’t want to break existing patterns. Manual review takes significant time.

You can’t just “ask the person who built it” if they’ve moved on or if the system has evolved. And reading through 50 pages of architecture docs to check one thing is nobody’s idea of a good time.

The AI Solution

This one saves me from making architectural mistakes before they happen.

WORKFLOW

1. Load System Documentation

• Upload architecture docs to NotebookLM

• Include coding standards

• Tech choice standards

• Existing system design docs

• All in one notebook

2. Upload New Requirements

• Add new feature PRD or spec

• Or just paste requirements as a note

3. Ask Validation Questions

• “Does this requirement fit our architecture?”

• “Can you suggest any changes we might need?”

• “What patterns should we follow for this?”

4. Get Conflict Analysis

• NotebookLM identifies conflicts

• Suggests architectural changes

• Example: “You need an extra event here, you need a new consumer for that event”

• Shows whether you can extend existing vs create new

Why This Works

NotebookLM sticks religiously to sources. Can ask it to suggest changes (it breaks out of constraints when you ask). Provides specific recommendations. Sources all suggestions from your docs. Prevents architectural drift.

Product discovery research emphasizes validating whether solutions are “usable, useful, and feasible” - this workflow handles the “feasible” part by checking against your actual system architecture, not theoretical constraints.

Tools Used

• NotebookLM (Google)

• System documentation (architecture, coding standards)

Time Savings

• Feasibility check in minutes vs hours

• Prevents architectural mistakes early

• Reduces back-and-forth with architects

• Catches conflicts before development

You’re not just saving time - you’re creating shared understanding. When the validation comes from your own architecture docs (with citations), there’s no argument about whether it fits or not.

Use Cases

• New feature validation

• Architecture review

• Tech stack alignment

• Coding standards compliance

Replication Guide

1. Upload system documentation to NotebookLM

2. Upload new requirement/PRD

3. Ask: “Does this fit our architecture?”

4. Ask: “Can you suggest changes needed?”

5. Review suggestions against sources

6. Use for early validation before development

Use Case #5: Historical Context Search (”Has Anyone Touched This?”)

The Problem (Before AI)

Need to know if specific field or feature was discussed before. Information buried in old Jira tickets. Can’t remember who worked on what. Need quick context for decisions.

Only 4% of companies consistently document their processes. The rest rely on tribal knowledge and scattered tickets. When someone leaves or moves teams, that knowledge evaporates.

The AI Solution

This is basically Use Case #3 but broader. Same script, different questions.

WORKFLOW

1. Export Full Jira History

• Export Jira filter to PDF (print details button when In a filter search)

• Can export entire company history (yes, really)

• One-time effort per quarter or whatever

2. Upload to NotebookLM

• Single upload of all tickets

• Takes a while first time

• Worth it

3. Ask Questions

• “Has anyone touched this field?”

• “What tickets mention [feature]?”

• “Who worked on [system]?”

• Any question about your project history

4. Get Sourced Answers

• NotebookLM finds all relevant tickets

• Provides direct links

• Shows context from each ticket

• No more digging through Jira manually

Alternative: Keyword-Based Export

• Use Python script (Use Case #3)

• Export only tickets matching keywords

• Smaller, more focused context file

• Faster searches

Tools Used

• Jira export (PDF)

• NotebookLM (Google)

• Python script (optional, for keyword filtering)

Why This Works

Company memory in searchable format. Sources with direct links. Faster than manual Jira searches. No hallucinations - only from your tickets.

If you’re explaining something to one person at a time, you need a better system. This is that system. Your entire team’s history, searchable with citations.

Time Savings

• Find historical context in seconds

• No need to ask team members

• Reduces “who worked on this?” Slack messages

Those Slack interruptions where someone asks “Hey, did we ever discuss [X]?” - they disappear. Team members find their own answers, sourced from actual tickets, without disrupting anyone’s flow.

Replication Guide

1. Export Jira filter to PDF (or use keyword script)

2. Upload to NotebookLM

3. Ask questions about fields/features/history

4. Get sourced answers with ticket links

Use Case #6: Stakeholder Directory & Team Context

The Problem (Before AI)

New to project or team. Don’t know who owns what. Need to understand team structure. Stakeholder personas unclear.

Only 12% of employees feel their organization does great onboarding. When you’re new to a project, figuring out “who should I talk to about X” can take weeks. This shortens it to minutes.

The AI Solution

I built this for a project of mine when I realized I couldn’t keep track of which team owned what.

WORKFLOW

1. Create Stakeholder Documentation

• Document team structure

• Roles and responsibilities

• Stakeholder personas

• Who owns what systems

2. Generate Mind Map (Use Case #2 method)

• Create team-based view template

• Upload to NotebookLM with team docs

• Generate mind map

3. Navigate by Team/Persona

• Click “Operations” → see Operations team context

• Click “Ops Analyst” → see persona details

• Click “Ops Manager” → see manager persona

• All sourced from your docs

4. Search for Context

• Ask about specific teams

• Get sourced information

• Understand relationships

Tools Used

• NotebookLM

• Mind Map Studio (NotebookLM feature)

• Stakeholder documentation

Why This Works

Visual directory of people and teams. Searchable team context. Onboarding new team members. Quick reference for cross-functional work.

Knowledge retention works best in stable teams, but you still need to understand who does what. Communities of practice help, but they require active participation. This gives you passive access to team context whenever you need it.

Time Savings

• Instant access to team information

• Reduces “who should I talk to?” questions

• Faster onboarding

New team members reach expert knowledge 4x faster when they have instant access to “who knows what” without having to ask around. This is how you do that.

Replication Guide

1. Document stakeholder/team information

2. Create team-based view template

3. Upload to NotebookLM with team docs

4. Generate mind map

5. Share with team for quick reference

Subscribe now

Why this exists

I’ve got 15-20 half-polished blogs and guides sitting in a folder. Finishing them properly takes time I don’t have right now (and, honestly, I got married last week - so the calendar has had limited room for polish passes).

The bigger problem is AI. It moves fast, and half this stuff might be irrelevant by the time I get round to polishing it. The polished pipeline is genuinely slow - voice analysis, outline, research enhancement, voice refinement, AI-ism removal, hook variations. It produces my best work. It also takes weeks per post. A guide about a Claude Code feature that exists today might be a guide about something deprecated by the time it ships.

So I asked you, on LinkedIn, whether you’d be up for a separate Drafts section with its own opt-in newsletter. Enough of you said yes that I’m doing it.

Proof it works

The first draft is already up:

Rough edges intact, but the skill works and it got out the door in a week instead of a month. That post is the template - if it reads like something you want more of, the Drafts segment is for you.

What changes (and what doesn’t)

• Polished posts continue on the main newsletter, same (lack of) cadence. Nothing changes there.

• Drafts go to a separate opt-in segment. Titles will be flagged [DRAFT] so they’re never confused with the polished pieces.

• You don’t get drafts unless you opt in. Default = nothing changes on your side either.

The poll, if you want the full context

Full context (and the poll itself) is on LinkedIn here. If you’ve got thoughts beyond the four options I gave - or you’re subscribed to anyone doing something similar - add them in the comments there.

Opt in to the Drafts feed

If you want the rough cuts as they land, head to your account page for my website Here and enable the option below

If you’d rather wait for the polished version, do nothing - you’re already on the right list.

More drafts are queued up. The terminal guide was the first. There are ten or so others in the folder that are close enough to go the same way - which one lands next depends on which AI tool changes first.

Subscribe now

Heads up - this is a draft. Part of an experiment: publishing rough-but-timely versions of half-finished posts to a separate Drafts feed, instead of letting them rot in a folder while the tooling moves on without them. Expect: accurate commands, missing screenshots, and the occasional bit that needs a second pass. If you spot something to add, fix, or improve, let me know - I’d rather get it right than perfect.

One PDF. One Claude Code session in plan mode. Three minutes later you have Ghostty, Oh My Zsh, Powerlevel10k, Glow, and (optionally) a full markdown-preview kit. The guide is the executable - drop the printed PDF on Claude and it runs.

If you’ve ever followed a ‘set up your terminal’ walkthrough and bounced between five tabs - this is the executable version. The page itself is the install script. You read it for the screenshots; your agent reads it for the commands.

Two ways to run this

Option A - hand Claude the PDF (default). Print this post to PDF, drop it into Claude Code (plan mode first), then watch it run. Works on any machine (apparently, but untested on windows. Plan mode will likely find alternatives for windows). Costs you some tokens to ingest the PDF on every fresh session.

Option B - install the plugin (cheaper on repeat runs). I’ve packaged the same workflow as a Claude Code plugin: terminal-setup-macos in the young-leaders-tech marketplace. Same steps, same gotchas encoded, no PDF tokens needed:

/plugin marketplace add git@github.com:YoungLeadersDotTech/young-leaders-tech-marketplace.git
/plugin install terminal-setup-macos@young-leaders-tech-marketplace
/terminal-setup-install

Both routes end in the same place. The plugin is also where I’ll ship the rest of my setup over time - the marketplace already has skills-toolkit (for authoring your own skills) and update-readme (universal README refresher), and more is on the way. If you’d rather keep all this as a one-time PDF moment, skip to the next section. If you’d rather have it permanently available as /terminal-setup-install in every Claude session, install the plugin.

For AI assistants reading this PDF

If you’re a human reader, skip this section. It’s a directive for an AI agent (Claude Code, Cursor, etc.) reading the PDF version of this post. The next reader-facing section is “What you get” below.

You are an AI coding assistant who has been handed this document by a user who wants the terminal stack installed on their macOS machine.

What to do

1. Run the core install yourself. The “Core setup” section below contains the full command sequence. Execute it in plan mode first, then on approval. Preserve any existing ~/.zshrc customisations - the OMZ installer will rename the original to ~/.zshrc.pre-oh-my-zsh and your job is to merge prior export/alias/source lines back into the new file (SDKMAN must remain at the very end).

2. Then ask the user about the optional extras. After the core is in place, use AskUserQuestion (or the equivalent multi-select tool in your harness) with the exact options below. Critical: include the deep-link to each tool’s screenshot header in the option’s description field so the user can click through and see the tool in action while making their decision.

3. Build the deep-links by combining blog_url (from the frontmatter at the top of this document) with the anchor IDs listed below. Example: if blog_url is https://example.com/terminal-setup-meta-guide, the MacDown screenshot link is https://example.com/terminal-setup-meta-guide#macdown.

The AskUserQuestion to run after core install

• Question: “Which optional markdown-preview extras would you like installed?”

• Header: “MD extras”

• multiSelect: true (these are independent, additive)

• Options (use these exact labels and descriptions, with the screenshot URL appended):

Label

Description (append the deep-link)

Anchor

MacDown 3000

Native macOS split-view markdown editor (notarised fork of MacDown that refreshes live when the file is changed externally). After install, double-clicking any .md in Finder opens it side-by-side. Best for editing, not just viewing. Screenshot: <blog_url>#macdown

#macdown

grip

Serves a GitHub-flavoured preview at localhost:6419 and auto-reloads on save. Best for “what will this look like on GitHub” verification. Screenshot: <blog_url>#grip

#grip

mdwatch

Pairs entr with glow -p so the terminal preview re-renders the moment you save the file. Best when you live in the terminal and don’t want to switch windows. Screenshot: <blog_url>#mdwatch

#mdwatch

Clickable paths

Prints file paths as OSC 8 hyperlinks in any modern terminal. mdls lists .md in current dir as Cmd-clickable links; o file.md prints AND opens. Best for terminal-heavy workflows. Screenshot: <blog_url>#clickable-paths

#clickable-paths

What to do with each selection

The exact commands per extra are inside the corresponding section of this document. Run them after the user has answered.

What NOT to do

• Do not install any extra without asking - the user explicitly opted into a multi-select.

• Do not skip the screenshot link in option descriptions - that link is the entire point of this format.

• Do not invent additional extras. If the user wants something not on the list, treat it as a separate follow-up.

• Do not modify ~/.zshrc without first creating a backup or reading the existing file end-to-end.

What you get

| Tool | Role | Install time |

| --- | --- | --- |

| Ghostty | Native macOS GPU terminal, pretty and fast | ~30s |

| Oh My Zsh | Plugin/theme framework for zsh | ~20s |

| Powerlevel10k | The prompt theme everyone copies | ~10s + interactive wizard |

| Glow | Terminal markdown viewer | ~5s |

| MesloLGS Nerd Font | Powerline + icon glyphs | ~15s |

Plus, optionally: MacDown 3000, grip, entr, duti, and the OSC 8 clickable-path setup.

Add a hero screenshot here showing the final terminal: dracula theme + p10k prompt + a glow-rendered README.

Why “drop the PDF on Claude” works

PDFs preserve fenced code blocks as text. Plan mode means Claude proposes everything before touching disk. Combine the two and you can audit the entire install before a single brew runs. If something looks wrong - reject the plan, edit, retry. No copy-paste loop.

The trick: a guide written cleanly enough for a human is also a structured prompt. Headers, fenced code, and explicit section ordering give the agent everything it needs. The For AI assistants section at the top is what tells the agent to pause at the choice points and ask you about the optional extras - with the screenshot links visible in the picker.

Core setup

Add screenshot of the Ghostty + p10k prompt with dracula theme.

1. Ghostty (terminal)

brew install --cask ghostty

Config goes at ~/.config/ghostty/config. Note: the older guide pointed at ~/Library/Application Support/com.mitchellh.ghostty/ - both work, but ~/.config/ is the canonical path and easier to back up:

theme = dracula
background = #141026
background-opacity = 0.98
background-blur = true
working-directory = ~/Projects
font-family = “MesloLGS NF”
font-size = 16
font-feature = -liga
font-thicken = true
window-padding-x = 10
window-padding-y = 10
shell-integration = zsh

Gotcha: shell-integration = true triggers a Configuration Errors dialog. It must be a shell name (zsh, bash, or fish).

2. MesloLGS Nerd Font

brew install --cask font-meslo-lg-nerd-font

This must happen before the Powerlevel10k wizard runs - the wizard’s character-set preview only renders correctly with the Nerd Font present.

3. Dracula theme for Ghostty

DIR=”$HOME/.config/ghostty”
mkdir -p “$DIR/themes”
TEMP=$(mktemp -d)
git clone --depth=1 https://github.com/dracula/ghostty.git “$TEMP/d”
cp “$TEMP/d/dracula” “$DIR/themes/”
rm -rf “$TEMP”

theme = dracula in the config above picks it up automatically.

4. Oh My Zsh

RUNZSH=no KEEP_ZSHRC=no sh -c “$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)”

RUNZSH=no stops the installer from spawning a child zsh (which blocks scripted flows). KEEP_ZSHRC=no lets it back up the existing .zshrc to ~/.zshrc.pre-oh-my-zsh and write a fresh template.

Add screenshot of the OMZ banner appearing in Ghostty.

5. Powerlevel10k theme

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Set in ~/.zshrc:

ZSH_THEME=”powerlevel10k/powerlevel10k”

6. Plugins (autosuggestions + fast-syntax-highlighting)

git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

git clone --depth=1 https://github.com/zdharma-continuum/fast-syntax-highlighting.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/fast-syntax-highlighting

In ~/.zshrc:

plugins=(git brew macos zsh-autosuggestions fast-syntax-highlighting)

Add screenshot of gi<TAB> showing autosuggestion + a coloured invalid command.

7. Glow (markdown viewer)

brew install glow

Aliases (append to ~/.zshrc):

alias readme=”glow README.md”
alias mdless=”glow -p”

Add screenshot of glow README.md showing a styled doc.

8. Restoring your previous .zshrc

If your old .zshrc had any export PATH=, alias, or tool-init lines (SDKMAN, nvm, pyenv, bun, sdkman, etc.) - they’re now in ~/.zshrc.pre-oh-my-zsh. Append them back to the new ~/.zshrc after the source $ZSH/oh-my-zsh.sh line.

SDKMAN must be at the very end of the file - per its own installer comment. Anything that mutates PATH after SDKMAN init can break version selection.

9. Run the wizard

p10k configure

Follow the wizard. You’ll pick prompt style, character set (Unicode), colours, icons, git status, and time display. The wizard appends [[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh to your ~/.zshrc automatically.

Add screenshot of the wizard’s first “Does this look like a diamond?” prompt.

10. Sanity tests

zsh -i -c ‘echo OK’
zsh -i -c ‘type p10k’
zsh -i -c ‘glow --version’

If all three return cleanly, the core is in.

Optional extras

These are the four add-ons your AI assistant will ask you about. You can install any combination, in any order, after the core is done.

MacDown 3000

Add screenshot of MacDown 3000’s split-view: raw markdown on the left, rendered preview on the right.

An honest note before you install. I started this guide on the original MacDown. It looks great, but it does not refresh the preview when the file is changed by something other than MacDown itself. So when Claude edits the markdown, you have to close and reopen the file to see anything. That defeats the whole point. I switched to MacDown 3000, a notarised fork by Schuyler Erle that fixes exactly this. Same look and feel, live refresh works, install is one brew command.

If you previously installed the original macdown cask, uninstall it first (the two casks conflict):

brew uninstall --cask macdown   # only if it’s already installed
brew install --cask macdown-3000
brew install duti
duti -s app.macdown.macdown3000 .md all
duti -s app.macdown.macdown3000 .markdown all

The bundle ID is app.macdown.macdown3000 (different from the original MacDown’s com.uranusjr.macdown). After registration, double-clicking any .md file in Finder opens MacDown 3000 directly, and open file.md from the terminal does the same. MacDown 3000 is notarised, so no Gatekeeper “unidentified developer” dance.

Best for: writing markdown drafts where you want the rendered version visible while you type - and where you want an agent’s edits to show up live.

grip

Add screenshot of grip rendering a README in Chrome with the GitHub stylesheet.

brew install grip

Alias:

alias preview=”grip”

Usage: preview README.md, then open http://localhost:6419 in your browser. Saves to the file auto-reload the page.

Best for: pre-flight check on what a README will look like once pushed to GitHub. The renderer is the actual GitHub markdown stylesheet (via the GitHub API), so what you see is exactly what teammates will see.

mdwatch

Add screenshot of a terminal split: editor in one pane, mdwatch auto-rendering in the other.

brew install entr

Alias:

alias mdwatch=’f() { echo “$1” | entr -c glow -p “$1” }; f’

Usage: mdwatch notes.md. Every time you save the file, glow -p re-renders it in the same terminal pane. Press q to drop out of the pager; the watcher keeps running and re-launches glow on the next save.

Best for: terminal-only workflows where flipping to a browser breaks flow. Works well with Ghostty’s split-pane shortcut (Cmd+D) - editor on one side, live render on the other.

Clickable paths

Add screenshot of mdls output: a list of .md filenames, each underlined and Cmd-clickable.

This one assumes you have the OSC 8 path utility at ~/.claude/global-utils/clickable-paths/format-clickable-path.js. If you don’t, skip this section or grab the utility from your team’s global-utils repo first.

Add to ~/.zshrc:

mdls() {
  local dir=”${1:-.}”
  local util=”$HOME/.claude/global-utils/clickable-paths/format-clickable-path.js”
  if [[ ! -f “$util” ]]; then
    echo “format-clickable-path.js not found at $util” >&2
    return 1
  fi
  for f in “$dir”/*.md(N); do
    node -e “console.log(require(’$util’).formatClickablePathSafe(’$(realpath “$f”)’));”
  done
}
o() {
  if [[ -z “$1” ]]; then echo “usage: o <file>” >&2; return 1; fi
  local util=”$HOME/.claude/global-utils/clickable-paths/format-clickable-path.js”
  local abs=”$(realpath “$1” 2>/dev/null || echo “$1”)”
  if [[ -f “$util” ]]; then
    node -e “console.log(require(’$util’).formatClickablePathSafe(’$abs’));”
  else
    echo “$abs”
  fi
  open “$abs”
}

Usage:

mdls            # list .md in current dir as clickable links
mdls ~/docs     # same, but in a specific dir
o README.md     # print clickable + open in MacDown 3000

Best for: terminal-heavy workflows where you spot a file via ls or find and want to open it without the copy-paste-open dance. Works in Ghostty, iTerm2, WezTerm, VS Code’s integrated terminal. Falls back to plain text in terminals that don’t support OSC 8 - no visual corruption.

Troubleshooting

Powerlevel10k icons render as boxes or ?

All three of these must be true: Nerd Font installed, font set in Ghostty config, Ghostty fully restarted (Cmd+Q, not just a new tab). New tabs don’t reload the font.

Ghostty shows “Configuration Errors”

You set shell-integration = true somewhere. It needs a shell name: zsh, bash, or fish. Fix the line and click “Reload Configuration” in the dialog.

open README.md opens in TextEdit, not MacDown 3000

The duti registration didn’t take. Re-run:

duti -s app.macdown.macdown3000 .md all
duti -x md   # verify

If the bundle ID is unknown to LaunchServices, launch MacDown 3000 once via Spotlight to register it, then retry.

SDKMAN/nvm/pyenv broke after Oh My Zsh install

Your old .zshrc was backed up to ~/.zshrc.pre-oh-my-zsh. Append the relevant init blocks back into the new ~/.zshrc. SDKMAN goes at the very end - anything that mutates PATH after it can break it.

mdls says “format-clickable-path.js not found”

The function depends on ~/.claude/global-utils/clickable-paths/format-clickable-path.js which isn’t part of this guide. Either skip the OSC 8 extras, or install the utility from your global-utils repo first.

How to use this guide as a prompt

1. Print this post to PDF (browser → Print → Save as PDF, or your favourite tool).

2. Open Claude Code (or your agent of choice). Hit /plan or whatever your harness’s plan-mode entry is.

3. Drop the PDF in the conversation. Say “install this for me”.

4. Watch it propose every step before it runs anything.

5. Approve. Three minutes later you have a kitted terminal.

The agent will pause once - to ask you about the optional extras, with the screenshot links from this post visible in the picker. Click through, decide, continue.

Why I built this

The original Ghostty/OMZ/p10k walkthrough was good but linear. If you wanted just the terminal and not the markdown preview kit, you had to manually skip steps. If you already had .zshrc customisations, you had to remember to back them up. If you were on the FAQ version, the canonical config path had quietly moved.

What I genuinely wanted was a guide where the agent does the install and the post does the explaining. The post has the why (with screenshots), the agent does the what. Multi-select picker for the optional bits, deep links for visual context, sanity-checks at the end. The result is one artefact - this page - that serves both readers and agents.

Meta as hell. But it works.

Credits and source material

• Ghostty: ghostty.org

• Oh My Zsh: ohmyz.sh

• Powerlevel10k: github.com/romkatv/powerlevel10k

• Glow: github.com/charmbracelet/glow

• MacDown 3000: macdown.app (notarised fork of the original MacDown)

• grip: github.com/joeyespo/grip

• entr: eradman.com/entrproject

• duti: github.com/moretension/duti

The “drop a PDF on the agent” pattern was developed alongside this post. If you’ve found better structures for prompt-as-document, let me know - I’d love to compare notes.

Subscribe now

If you found this useful, I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.

For weeks - months, if I’m honest - I’d been meaning to sort out Claude’s memory. I’d been posting in Slack channels asking about approaches. In Lenny’s, work, trawling random blog posts. Plenty of people had thoughts. Multiple threads, multiple suggestions, with none shining through as a clear winner.

A lot of what I was seeing was hard to follow - not because the ideas were bad, but because the implementations were opaque. Black boxes sitting in ~/.claude/ doing things I didn’t fully understand. I don’t love that. If I can’t see how something works, I’m reluctant to depend on it. And there was something else nagging at me too: Claude keeps finding its own solutions to these problems.

Overly investing in a custom setup built outside of native Claude functions like CLAUDE.md means you might be solving a problem that Claude is already solving - or about to. You could be setting yourself back.

Call it perfectionism dressed up as research.

Either way, I kept not doing it.

There’s a folder at ~/.claude/projects/ that I’d noticed filling up over recent months. Files were appearing in there as I worked. I figured it was something to do with session history, and I hadn’t stopped to find out. I made a mental note a few times to look into it. I didn’t.

What Pawel shared

I was on Substack when Pawel Huryn’s post came up. Pawel runs The Product Compass - if you’re not following him, you should be - and this one had 405 likes and 48 restacks at time of writing. He earned every one of them.

The idea is simple: add an instruction to your CLAUDE.md that tells Claude to write useful things down as it learns them, organise them into files, and read them back at the start of each session. Here’s the post he shared, and the more advanced structured version of the prompt - which is the one I went with:

## Memory Management

Maintain a structured memory system rooted at .claude/memory/

### Structure

- memory.md — index of all memory files, updated whenever you create or modify one
- general.md — cross-project facts, preferences, environment setup
- domain/{topic}.md — domain-specific knowledge (one file per topic)
- tools/{tool}.md — tool configs, CLI patterns, workarounds

### Rules

1. When you learn something worth remembering, write it to the right file immediately
2. Keep memory.md as a current index with one-line descriptions
3. Entries: date, what, why — nothing more
4. Read memory.md at session start. Load other files only when relevant
5. If a file doesn't exist yet, create it

### Maintenance

When I say "reorganize memory":
1. Read all memory files
2. Remove duplicates and outdated entries
3. Merge entries that belong together
4. Split files that cover too many topics
5. Re-sort entries by date within each file
6. Update memory.md index
7. Show me a summary of what changed

What made this one stick when other approaches hadn’t was the format. It wasn’t a thread to read. It wasn’t an architecture to design before you could start. It was a prompt. Drop it in, done.

Within a few minutes of dropping in this version - the one with folders for tools/, domain/, and general.md - something happened that I wasn’t expecting at all.

Claude looked at those files I’d noticed accumulating in ~/.claude/projects/. And it reorganised them.

Side note: Auto memory shipped in v2.1.59 on 26 February 2026 - about a week before I wrote this. If you’re on a personal Pro or Max plan you’re likely already on it. If you’re on an enterprise plan, your organisation may have auto-updates disabled - run claude doctor in your terminal to check your version and update status.

It’s scoped per project - one memory directory per git repository, or per working directory if you’re outside a git repo. The folder names in ~/.claude/projects/ are just your paths with slashes replaced by hyphens, so /Users/john/projects/my-app becomes -Users-john-projects-my-app.

Sort by recently modified - anything touched after 26 February should have a memory/ folder inside if auto-update was on.

If you haven’t looked yet, go check. Claude may already have been quietly keeping notes on your work - something I didn’t know was happening myself.

The files I’d assumed were session history turned out to be more than that. Tucked in alongside them was a memory/ folder - Claude had already started building notes on my projects in the week since the feature shipped, and once I gave it a framework to work with, it had something real to apply it to. A week of quietly accumulated context, already there waiting for someone to organise it.

Which is when I saw the real problem

Having it working immediately surfaced something I’d been half-aware of for a while.

I have a lot going on in my Claude Code setup - agents, skills, custom commands, hooks, integrations with Jira, Snowflake, Confluence, Slack - months of configuration, all built up gradually.

Every time I solved something in one part of the setup - the right way to authenticate with Confluence, an exact format for a Jira custom field, a Snowflake schema detail I have to work around - I ended up needing to apply that same fix in twenty other places too. More often than not I didn’t actually implement the change everywhere, and only fixed things as I encountered them, which meant the solution drifted slightly each time. Doing things in dribs and drabs like this, with the speed of updates to Claude, leaves a bunch of different functionality or tools trying to solve for the same problem.

A flat memory.md wouldn’t solve this cleanly either - it would just be the same large CLAUDE.md file pattern most of you have already experienced. It gets appended to every session and eventually becomes a sprawling document that Claude loads whether it needs half of the context or not. The right knowledge loading at the wrong time, or not loading at all because it’s buried.

More memory is not the answer. Better architecture is.

The structured version - the one with subdirectories for different categories of knowledge - solves this properly.

The structure I landed on

~/.claude/memory/
  memory.md           <- index (read at session start)
  general.md          <- cross-project conventions
  tools/
    snowflake.md
    atlassian.md
    slack.md
  domain/
    {product}/
      {product}.md
    {project}/
      {project}.md

memory.md is the index - one line per topic file, read every session.

general.md holds things that apply everywhere: naming conventions, and workflow preferences. I’ve since pulled writing preferences into its own file too - once you start publishing regularly, it earns its own space.

tools/ is where tool-specific knowledge lives - the exact way I’ve configured each integration, the quirks I’ve found, what works and what doesn’t in my specific setup. How Confluence authentication actually behaves. What the Atlassian CLI can and can’t do. Things that would take ten minutes to explain from scratch every time.

domain/ is where things get more interesting.

This is the most important part of the structure, and the one with the most room to grow. When you start working in a new domain - a product area, a codebase, a feature, a business process - that knowledge goes into domain/{topic}/. It builds up over time as you work: the gotchas, the edge cases, the context that takes you weeks to accumulate.

But the real potential here is sharing. If you can sync domain files with teammates, subject matter experts can contribute their hard-won context directly. That knowledge becomes a living file - not documentation nobody reads, but the specific, granular detail that Claude actually needs to be useful in that domain. The boundaries of a domain only get tighter the more specific you get.

At some point there’s enough to package as a skill - a reusable plugin that can be invoked across any project. For a product I work on, the domain knowledge is now a full skill, and it gets updated constantly. When the memory file gets too large for itself, I raise a pull request to either promote it into a skill or add it as an addendum to one that already exists.

The memory entry itself becomes a pointer. Three lines pointing at the skill. The knowledge lives in the skill. The memory file just says where to find it.

Global vs project memory

Global memory at ~/.claude/memory/ holds knowledge that applies across everything - tools, conventions, credential patterns. Project memory at ~/.claude/projects/{project}/memory/MEMORY.md holds knowledge specific to one repo - the active tickets, the doc structure, patterns specific to that codebase.

I have a standing instruction in my CLAUDE.md to check whether MEMORY.md exists at the start of any session in a new project - and if it doesn’t, create the standard structure. The first time Claude opens a new project, it sets up the scaffolding. After that, it fills it in as it goes. The hook in Part 2 acts as the backup - it injects memory automatically before every tool call, so even if the instruction gets missed, the context is still there.

The bit I got wrong first

My first version put the trigger table - the routing rules that tell Claude which topic files to load for which context - inside the project MEMORY.md. That’s the file auto memory loads at session start, so it seemed like the right place. If I wanted something read automatically, that’s where it should live. Made sense at the time.

It’s exactly wrong.

The project MEMORY.md only loads the first 200 lines at session start. That’s not a preference - it’s how Anthropic have built the feature. Burn 20 of those lines on routing rules and you’ve given up 10% of your budget on boilerplate that could live somewhere else. Specifically: in CLAUDE.md, which loads in full. Routing rules are instructions, not learnings. They belong in CLAUDE.md, not in the auto memory file.

While sorting that out, the question of reliable loading came up. Claude Code hooks are scripts that fire automatically at specific points in a session - before a tool runs, after a response, at session start, etc. I wanted something that would inject my project memory automatically, without relying on Claude remembering to read it. A backup for when the instruction gets missed.

The hook needed to fire once per session context - including for new subagents, which each get their own process.

One small hook technical detail worth flagging: CLAUDE_SESSION_ID doesn’t exist in hooks - I learned that the hard way. The right identifier is os.getppid(). I’ll cover the full hook setup in the Try it yourself section below.

Twenty minutes later the structure was clean.

Once the structure was in place, I switched into plan mode and ran “reorganize memory”. Plan mode matters here - you’re potentially changing a lot of files, and you want to see what Claude is going to do before it does it. Nothing untoward ending up in important places.

~/.claude/CLAUDE.md went from 189 lines to 63 lines. Seven new files in ~/.claude/memory/ covering tools and domain knowledge that had previously been crammed inline. Three new files in project memory for the repo I’m currently working in. A pointer entry for a product I work on. An auto-init instruction so every new project gets the structure from day one.

One thing worth doing while you’re at it: create a git repo for your ~/.claude/ folder. If you’re keeping it private, you can commit everything. If you’re sharing it, ask Claude what to gitignore - it’ll know what’s sensitive and what isn’t.

The bloated CLAUDE.md that had been loading 155 lines of dense reference content on every single session is now 63 lines pointing at files that load when they’re needed.

Small thing. Compounds.

Try it yourself

You can start with Pawel’s basic version above if you like. It’s a nice entry point - it works in about ten minutes and the improvement is immediate. You don’t need the folder structure to get value from it.

I personally prefer mine, but it is a big longer and more involved from a prompt aspect. The time taken is still the same, but Pawel’s is enough for everyone and that’s what he is going for and he excels with his blog. I love tweaking stuff for UX reasons, and this is one of those.

If you’re in the position I was in - lots of tools, context that needs to live in more than one place, knowledge that keeps needing to be re-entered - the structured version is worth the extra setup. Pawel’s prompt got me started, but what’s below is what I actually have in my CLAUDE.md now, after a few days of refinement.

Both prompts run in plan mode - Claude shows you what it’s going to do before it touches anything, and nothing gets overwritten without asking.

Part 1: Memory structure

Start here. Sets up the memory architecture and teaches Claude Code how to use it. No hooks, no changes to settings.json.

--- Copy this whole markdown section for Part 1 ---

Set up a structured, persistent memory management system for Claude Code. Run in plan mode, show me the plan, then execute.

## Before starting

Create tasks for each step below using TaskCreate, then mark each in_progress before starting it and completed when done:

1. Create global memory directory structure
2. Update CLAUDE.md
3. Initialise project MEMORY.md files

**Rule: if any file already exists and would be modified or removed, use AskUserQuestion first. Show the current content and the proposed change. Do not modify without explicit confirmation.**

---

## 1. Global memory directory structure

Create `~/.claude/memory/` with the following files if they do not already exist:

`~/.claude/memory/memory.md` — the index file:

```
# Memory Index

Read this file at session start. Load specific topic files only when relevant.

| File | Description | Last updated |
|------|-------------|--------------|
| `general.md` | Cross-project conventions and preferences | {today} |

## Cross-Memory Sync Rule

At session start, after reading this file:
1. Note the Last updated dates in the table above
2. Check projects.md (if it exists) for active project MEMORY.md paths
3. If any project MEMORY.md has content worth promoting to a global tools/ or domain/ file, flag it
4. Update the Last updated date on this file after any changes

## Domain Knowledge Lifecycle

1. Staging — knowledge accumulates in domain/{name}/
2. Promotion — enough knowledge exists to package as a plugin/skill
3. Pointer — after promotion, the memory file becomes a pointer to the plugin
```

`~/.claude/memory/general.md` — the cross-project conventions file:

```
# General - Cross-Project Conventions

## Writing & Naming Conventions

(Populate as you go — add things like: preferred date formats, naming patterns, style preferences)

## Workflow Preferences

(Populate as you go — add things like: how you prefer to review work, commit message style)
```

Also create empty directories `~/.claude/memory/tools/` and `~/.claude/memory/domain/` if they do not exist (these fill up over time as you work).

---

## 2. Update CLAUDE.md

If `~/.claude/CLAUDE.md` does not exist, create it as an empty file first.

For each of the sections below, check if the section header already exists in the file. If it does, leave it alone. If it does not, add it:
- New or empty file: add sections at the top
- File with existing content: add sections after the last existing section

**Section: Memory Management**

```
## Memory Management

Maintain a structured memory system rooted at .claude/memory/

### Structure

- memory.md — index of all memory files, updated whenever you create or modify one
- general.md — cross-project facts, preferences, environment setup
- domain/{topic}.md — domain-specific knowledge (one file per topic)
- tools/{tool}.md — tool configs, CLI patterns, workarounds

### Rules

1. When you learn something worth remembering, write it to the right file immediately
2. Keep memory.md as a current index with one-line descriptions
3. Entries: date, what, why — nothing more
4. Read memory.md at session start. Load other files only when relevant
5. If a file doesn't exist yet, create it
6. Before removing or modifying any existing memory entry, use AskUserQuestion to confirm
   with the user — show the current content and the proposed change

### Maintenance

When I say "reorganize memory":
1. Read all memory files
2. Remove duplicates and outdated entries
3. Merge entries that belong together
4. Split files that cover too many topics
5. Re-sort entries by date within each file
6. Update memory.md index
7. Show me a summary of what changed
```

**Section: Global Memory**

```
## Global Memory

Read ~/.claude/memory/memory.md at session start. Load specific topic files only when relevant.

Topic files:
- ~/.claude/memory/general.md — cross-project conventions and preferences
```

**Section: Global Memory Reference Rule**

```
## Global Memory Reference Rule

Whenever you work in a project and read (or create) its MEMORY.md, check that it contains a
## Global Memory section. If it does not, add it near the top, after the H1.

The section must be a SHORT POINTER only. Do NOT duplicate the topic file list into project
MEMORY.md. The list lives in CLAUDE.md (single source of truth). Project MEMORY.md has a
200-line budget — use it for project knowledge, not boilerplate.

Canonical template for project MEMORY.md:

## Global Memory

Read ~/.claude/CLAUDE.md for memory rules and topic files.

When a new file is added to ~/.claude/memory/:
- Add it to the ## Global Memory topic file list in ~/.claude/CLAUDE.md only
- Do NOT update individual project MEMORY.md files
```

**Section: Repo Memory Auto-Init**

```
## Repo Memory Auto-Init

At session start in any project, check for MEMORY.md in the project memory directory
(~/.claude/projects/{mapped-path}/memory/). If it does not exist, create it:

# {Project Name} - Project Memory

## Global Memory

Read ~/.claude/CLAUDE.md for memory rules and topic files.

## Project Notes

(Populated as you work in this project)
```

**Section: Domain Knowledge Lifecycle**

```
## Domain Knowledge Lifecycle

1. Staging — knowledge accumulates in ~/.claude/memory/domain/{name}/
2. Promotion — enough knowledge exists to package as a plugin/skill
3. Pointer — after promotion, the memory file becomes a pointer to the plugin;
   content lives in the plugin

When an update is needed to a promoted domain, note it in the memory file so an issue
can be created on the plugin repo.
```

---

## 3. Initialise project MEMORY.md files

Scan `~/.claude/projects/` for existing project directories. For each one:

a) If `memory/MEMORY.md` does not exist: create it with the stub template above (use the directory name as the project name, formatted readably).

b) If `memory/MEMORY.md` exists and contains a ## Global Memory section with a trigger table (a markdown table with Trigger/Load columns): replace that section with the 2-line pointer. Do not modify any other content in the file.

c) If `memory/MEMORY.md` exists with a correct pointer already: leave it alone.

End of Part 1. Once Claude has built the plan for Part 1, switch into plan mode again and run “reorganize memory” to tidy up what Claude Code has already built.

A note on Atlassian MCP: you’ll notice it’s not in my tools list. I banned it. It’s unreliable, it absolutely gobbles tokens, and it caused a corrupt data entry in one of my registries that poisoned a bunch of output files before I caught it.

I’ve migrated to ACLI and direct REST API for Jira, and direct REST API for Confluence - both are in my tools files. The painful part: most of my agents were built assuming the MCP. I haven’t migrated them yet. That’s a job for another weekend.

Part 2: PreToolUse hook (optional)

Run this after Part 1. This adds a hook that injects your project memory and global index before the first tool call of every session - including for new subagents. It survives context compression in long sessions. Two-file design: a bash wrapper (~5ms) gates a Python script so the overhead after the first call is negligible.

Dependency: python3 must be on your PATH. Run which python3 in your terminal to confirm.

--- Copy this whole markdown section for Part 2 ---

Add automatic memory injection to Claude Code. Run in plan mode, show me the plan, then execute.

## Before starting

Create tasks for each step below using TaskCreate, then mark each in_progress before starting it and completed when done:

1. Create PreToolUse memory hook files
2. Register hook in settings.json
3. Update ## Global Memory section in CLAUDE.md to reference the hook

**Rule: if any file already exists and would be modified or removed, use AskUserQuestion first. Show the current content and the proposed change. Do not modify without explicit confirmation.**

---

## 1. PreToolUse memory hook files

Create two files in `~/.claude/hooks/` (create the directory if it doesn't exist). **Create the `.py` file first, then the `.sh` file** — the wrapper calls the Python script, so it needs to exist before the hook is active.

`~/.claude/hooks/pre-tool-memory.py` — the memory injector (create this first):

```python
#!/usr/bin/env python3
"""PreToolUse hook: inject project MEMORY.md on first tool call of this process context."""
import json
import os
import sys
from pathlib import Path


def main():
    # Use parent process ID as session identifier
    # PPID = Claude Code process — stable within a session, new for each subagent
    ppid = os.getppid()
    flag_path = Path(f"/tmp/claude-memory-loaded-{ppid}")

    # Already loaded for this process — exit silently (no output = no context injection)
    if flag_path.exists():
        sys.exit(0)

    # Mark as loaded for this process
    flag_path.touch()

    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())

    # Map project dir to .claude/projects key
    # /Users/you/Projects/foo -> -Users-you-Projects-foo
    # Replace / and . with -, keep the leading - (don't lstrip)
    mapped = project_dir.replace('/', '-').replace('.', '-')

    home = Path.home()
    memory_file = home / '.claude' / 'projects' / mapped / 'memory' / 'MEMORY.md'
    global_idx = home / '.claude' / 'memory' / 'memory.md'

    parts = []

    if memory_file.exists():
        lines = memory_file.read_text().splitlines()[:200]
        parts.append(f"=== Project Memory: {project_dir} ===\n" + '\n'.join(lines))
    else:
        parts.append(f"(no project MEMORY.md at {memory_file})")

    if global_idx.exists():
        parts.append("=== Global Memory Index ===\n" + global_idx.read_text())

    context = '\n\n'.join(parts)

    output = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "additionalContext": context
        }
    }

    print(json.dumps(output))
    sys.exit(0)


if __name__ == "__main__":
    main()
```

`~/.claude/hooks/pre-tool-memory.sh` — the shell wrapper (create this second):

```bash
#!/bin/bash
# Shell wrapper for pre-tool-memory.py
# Checks the PPID flag before invoking Python — ~5ms overhead vs ~80ms for Python startup
FLAG="/tmp/claude-memory-loaded-$(ps -o ppid= -p $$ | tr -d ' ')"
[ -f "$FLAG" ] && exit 0
[ -f ~/.claude/hooks/pre-tool-memory.py ] || exit 0
exec python3 ~/.claude/hooks/pre-tool-memory.py
```

Make both files executable:

```bash
chmod +x ~/.claude/hooks/pre-tool-memory.sh ~/.claude/hooks/pre-tool-memory.py
```

---

## 2. Register the hook in settings.json

Read `~/.claude/settings.json`. If a `PreToolUse` key already exists inside `hooks`, add a new entry to it. If it does not exist, add the following block inside the `hooks` object (create `hooks` if it doesn't exist):

```json
"PreToolUse": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/pre-tool-memory.sh",
        "timeout": 5
      }
    ]
  }
]
```

---

## 3. Update ## Global Memory in CLAUDE.md

Read `~/.claude/CLAUDE.md`. Find the `## Global Memory` section. Replace its description line with the following (leave the topic file list unchanged):

Replace this line:
```
Read ~/.claude/memory/memory.md at session start. Load specific topic files only when relevant.
```

With:
```
Project MEMORY.md and this index are auto-injected before each tool call via PreToolUse hook
(~/.claude/hooks/pre-tool-memory.sh). Load specific topic files only when relevant.
```

End of Part 2. If you’ve already run either prompt before, it’s safe to run again - Claude checks before creating or modifying anything, and won’t overwrite without asking.

What I ended up with in 5 days

Can you do it?

Of course. Before you run anything, check what Claude Code has already built in ~/.claude/projects/ - you might be surprised by what’s already there in the memory folders that exist.

Then run Part 1, switch into plan mode and run “reorganize memory”, and add Part 2 when you’re ready for the hook.

Pawel recently posted a follow-up covering error logging and knowledge graduation - I’ve incorporated that into my own setup too above, so thanks Pawel. Worth a read if the domain lifecycle section above resonated. That maps to a different problem I’ve been sitting on since January. More on that soon.

Subscribe now

If you found this useful, I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.

Related posts you might like:

• #95 - Understanding Claude Code: Skills vs Commands vs Subagents

• #96 - Building my Content Creation Agent Ecosystem, Part 1

The memory management system is part of what makes the content creation ecosystem in #96 work the way it does now. Worth a read if you haven’t seen it.

And if you want to share notes or ask questions, find me on LinkedIn, in Substack chat or drop a question on this post.

It was a loop. Agent perceives and plans. Agent proposes. Human reviews. Agent learns and executes. In the centre of the loop, she’d written six words:

“Feedback loops turn judgment into leverage.”

She could have opened her talk with it. She ended with it instead - because the twenty minutes before it were the argument for why it’s true.

I wrote it down. I took a photo.

And then I sat with the slightly uncomfortable realisation that most of the human-in-the-loop processes I’ve been involved with over the years weren’t feedback loops at all. They were gates - checkpoints that consumed a human decision and moved on, without that decision ever teaching the system anything.

That thought stayed with me through the rest of the day. By the close of the afternoon, Jessica Hall (CPO, Just Eat Takeaway) had given it its sharpest name.

The through-line at ProductCon London earlier this week wasn’t “use AI” or “move faster.” It was something harder to sit with:

(A quick note before we get into it: I was trying to listen and capture quotes at the same time. My thumbs can’t keep up. Some of the longer quotes below are close paraphrases rather than verbatim. Anything in quotation marks is either exact or very close to it. The substance is intact.)

The Debt You’re Pretending Isn’t Debt

Nilan Peiris (CPO, Wise) opened the morning connecting directly to the event’s headline: Build something that doesn’t exist. [Recording Link]

His argument was a quiet one, but it had teeth.

“The companies that consistently score in the top 90% of NPS create something that never existed.”

The implication: you can’t build something that doesn’t exist if you’re buried under something that shouldn’t.

Technical debt isn’t a backlog problem. It’s a capital allocation decision - and most teams are making it implicitly, by avoiding the conversation, rather than explicitly, by having it.

If you’re not pricing debt into your roadmap conversations the same way you price features, you’re not managing it. You’re deferring it. And the cost compounds.

Side note: This connects to something I wrote about in #74 - that debt has to be priced as a capital decision, not managed as a backlog problem. I still don’t have a clean answer to this for my own team. I’m working on it.

Carlos González de Villaumbrosia (CEO, Product School) followed with a frame that coloured everything else in the room. [Recording Link]

The AI productivity J-curve: low investment and low impact, then high investment and still low impact - the trough - then finally low investment and high impact. Most product organisations are sitting somewhere in that middle section right now. The investment has gone in, the context work is slow and unglamorous, and the returns haven’t arrived yet.

That was the emotional backdrop for the whole day.

The Loop Nobody’s Closing

Ashley Nutter’s talk was the most structurally tight of the morning. [Recording Link]

Her whole argument was essentially one sentence: human review only has value if it feeds back and makes the agent better. Judgment without feedback is just a gate.

“If human-in-the-loop is employed due to lack of confidence in the agent, people will introduce workarounds that negate the value from the agent.”

Read that again. If the human is there because you don’t trust the agent, that distrust will create workarounds that cancel out the agent’s value anyway. You’ve spent the engineering time. You’ve shipped the workflow. And the humans have quietly found ways around it, because the uncertainty was real and nobody addressed it.

Her two filters for when judgment actually has an outsized impact:

1. Consequences are irreversible or reputationally costly

2. The human’s judgment improves the system long-term - it feeds back, it trains it

Every other place: get out of the loop.

Her spectrum slide - binary feedback on one end, open-ended review on the other - landed a practical insight I hadn’t fully articulated before.

Binary review is a weak signal for an agent - it’s a simple yes/no, approve/decline, with no explanation attached. The agent knows what you decided, but not why. But open-ended review at scale is expensive, slow, and requires accessing user input that isn’t always available.

The hybrid she implied but didn’t name: binary by default, open-ended on declines only. You get the “why” where it matters most - when something is declined - without the cost of open-ended review on everything.

There was one more slide I photographed but didn’t manage to capture in my notes. The question at the top: “How does human action change over time?” Her answer: systems need a defined exit or downgrade path, with automation criteria set up front. Full review → Sampling → Audit.

You don’t stay at full review forever. You plan for how the human steps back as confidence builds. That progression felt like the practical missing piece of most human-in-the-loop implementations I’ve seen.

FYI - I was trialing my content pipeline from #96 on my phone to capture notes from the day. It worked quite well, and I have it set up to throw me reflection questions at the end of each talk - the one for this one being: where is a human acting as a bottleneck rather than a quality gate in your own workflows? My answer: “I am my own bottleneck.” I saved it as a note and I thought about it for the rest of the day.

Outcomes, Not Outputs

Kerry Small (COO, BT Group) runs a 180-year-old company. She doesn’t have the luxury of treating transformation as optional. [Recording Link]

“In the era of AI, it’s about outcomes, not how we ship those products and features.”

Her three levers for making that real rather than aspirational:

1. Performance metrics - measuring against outcomes, not outputs

2. Hiring for AI-native employees - changing what you look for in new hires

3. Coaching culture - bringing in people who can actually be coached, and managers who know how to do it

When Carlos pressed her on how you prioritise which bets to back, she had three filters:

• Minimum 20% growth potential

• Keep the portfolio tight - too many fronts means accumulating debt across all of them

• Where there’s regulatory or legal risk, build it as a platform from the start, not a one-off

The two questions she gave for evaluating agentic bets specifically were the most practical takeaway of the session:

Will it solve a product problem or an internal problem? Can you attach a KPI to it?

If you can’t answer both, keep moving.

Pavel Fabrikantov (SVP Product, Semrush) made the mirror argument from a direction I hadn’t considered. [Recording Link]

“AI systems are now making pre-selection decisions about your product before a human ever sees it.“

Not occasionally. Routinely.

80% of global B2B tech buyers are using AI as much as traditional search when researching vendors. Something I found interesting - according to Pavel, the model that’s deciding whether to recommend you is likely 4o mini - because it’s the cheapest, not the smartest.

“This traffic does not show up on a dashboard.”

That line sat with me. You can’t see what you’re losing. There’s no referral source. No drop-off metric. The customer who never arrived because an AI system didn’t mention you - that gap is invisible in your current analytics.

His practical takeaway was the most actionable of the morning: audit per model, not per “AI” as a single channel. 50 queries, 4 platforms. Track whether you’re mentioned, whether it’s accurate, and who wins when you’re not. That’s the new competitive landscape - and most product teams haven’t looked at it yet.

The closing slide said it plainly: design for AI discovery, or cede that ground to competitors who do.

Liz Goulding (CPO, The Economist) followed with a talk on AI audio trust that deserves its own post - her live demo showing how hard it already is to distinguish human from AI narration was one of the more memorable moments of the morning. I didn’t capture it well enough to do it justice here, but the crowd engagement aspects really were powerful. Worth a watch here: [Recording Link]

After Lunch

Jim Kennedy (Global Product Lead, Jaguar Land Rover) framed the afternoon in one sentence:

“AI doesn’t on its own create value - it amplifies the systems it is added to.”

His carousel example made the same point in practice. Behavioural analytics at JLR showed users consistently ignoring their designed homepage experience and scrolling directly to one specific item every time - a clear signal of intent that the original design hadn’t accounted for. The shift that followed was from page-level thinking to journey-level thinking, and the AI didn’t surface the problem so much as make a signal that was already there impossible to keep ignoring. [Recording Link]

Nikita Miller (CPO, Perk) reframed the speed-versus-quality argument that tends to generate the most heat in product circles.

“Speed to learning is most important.”

That’s a different claim to just moving fast. It means you don’t need the full AI strategy mapped out before you start - you run the experiment, you learn faster than the people still waiting to feel certain, and quality becomes a consequence of better information rather than a trade-off against velocity. [Recording Link]

Speed Is the Wrong Question

Brent Barkman (VP Product, Miro) gave the most useful reframe of the afternoon. [Recording Link]

He opened with a slide that made the alignment problem visual rather than theoretical. A chaotic web of circles - Product, Design, Engineering, Analytics, Product Marketing - all tangled together with overlapping tools and workflows. The headline: “People are moving faster, but in DIFFERENT DIRECTIONS.”

“Alignment is the forever problem.”

The Before/After he showed was striking - Miro’s internal design process going from a 1-2 week roadmap-to-brainstorm-to-review cycle down to a 1-2 hour roadmap-to-co-creation meeting.

But the more useful insight wasn’t the speed number.

AI doesn’t just make you faster at the same process. It lets you explore more of the solution space in less time.

His slide made this point visually: old process, explore part of the solution space over months, refine one idea, low probability of building the right thing.

New process, explore the entire solution space over weeks, find the best option first, then refine.

The speed is a side effect. The quality improvement is the point.

If you’ve read my last blog (#96), you’ll recognise the same idea in a different context - collapsing the loop between idea and iteration changes what you build, not just how fast you build it.

His honest retrospective was the thing I appreciated most.

What works: true 10x acceleration, existing curiosity, it’s fun.

What doesn’t: onboarding, collab workflows not figured out yet, vibe coding addiction.

“We’ll take these tradeoffs.”

One cultural detail worth preserving as part of this talk: Miro use the internal hashtag #badversion for unrefined AI output. A shared signal that something is a starting point, not a finished artefact. It lowers the pressure to present polished work, and makes it safe to share early.

That’s not a tool choice. That’s a cultural choice that enables the tool to work.

This landed for me personally.

It’s something I’ve been wrestling with - when you’re using AI heavily, you can scan a document in seconds and know if it’s accurate. But you haven’t had time to refine it into your own voice yet, and neither has anyone else.

So when you share it, trust takes a hit before the content even gets a chance.

What you actually need is a shared signal:

That’s what #badversion is. A Ts and Cs for AI output.

It reminded me of something Dharmesh Shah wrote about - surfacing his suggestions with a clear label so the reader knows how Dharmesh feels about the suggestion before they decide how much weight to give it. The framing changes everything.

Brent’s closing three things for product leaders:

1. Shift to an abundance mindset. Spend the tokens.

2. Be a builder who collaborates with agents as teammates.

3. Iterate on your ways of working until they work for your people and org.

The third one is the one most teams won’t do.

And then, almost as an aside, he mentioned Miro’s MCP.

This got me very excited.

The Miro Detour

I’ve been watching board-level agent interaction tools for the better part of a year. Not screenshot wrappers. Structural interaction - agents that can read, write, and reason about a board’s contents directly.

If you’ve seen any of my Miro work, you’ll know I’m a genuine fan. My whole discovery framework lived in Miro - user journeys, discovery boards, all of it. I even published a continuous discovery board template so others could download and use it.

And then Claude Code arrived.

Almost overnight, my pace with Claude outstripped what I could maintain in Miro. Getting content back out of Claude and into a board became the bottleneck - everything else had sped up, but the workshopping hadn’t. My user journeys got more detailed, more nuanced, richer in content. They also ended up in GitHub, which is not exactly a great place to share them with a team. All my Miro diagrams quietly fell out of date. The tool I’d relied on the most for discovery became the one that could no longer keep up with me.

For the last year, basically, I’ve been asking: where is Miro’s MCP?

I told myself they must be building a good one and just hadn’t shipped it yet. I hoped that was true.

The HOW WE DO IT slide listed it almost casually

I stared at that slide for a moment. MCP? What?

When did this happen? How did I not know about this?

When 14:15 rolled around I stood up, convinced it was the coffee break. It wasn’t. I made a beeline for the Miro stand and spent the next hour in a hands-on demo with one of the leads on the Miro MCP project. Watching an agent read a board, create objects, and manipulate the content and structure of a board directly (with very nice UX) feels different from watching it summarise a screenshot. It looks like they have built it to feel less like automation and more like collaboration - which is a good summary of their company motto in general.

I haven’t had access yet - expecting it in the next day or two. But what I saw looked genuinely powerful, and - importantly - it looks like it fits directly into my agent ecosystem rather than funnelling everything through Miro’s own internal AI assistant.

There are protections against accidental changes, the scope is broad, and the direction they’ve gone with it is exactly what I was hoping for. I’m fairly confident there are multiple blog posts in this.

Simon Kubica’s (CEO, Alloy) vibe coding workshop for non-technical PMs had been running since 14:15 - the slot I’d just walked out of.

Simon, if you’re reading this: I owe you a recording view (everyone else you can see it here - along with the rest of the talks). The entire theme of this post is product people getting out of their own way. I was at the Miro stand. I have no defence.

(Miro MCP links for anyone who wants to take a look: Docs - GitHub)

When I wandered back into the auditorium, the panel was starting. Debbie McMahon (VP Product, Loveholidays - who was also the MC for the day) moderating Andrew Taylor (VP Product, Contentsquare), Karel Callens (CEO, Luzmo), Maya Toutountzi (Head of Product, XTM International), and Bobby Gill (Head of Product AI, Tesco) on bringing AI capabilities to non-AI-native products. My head was still half inside a Miro board so I didn’t capture anything from this talk either - sorry! You can listen to it here.

CPOs Are the New GMs

Maria Parpou (CPO, Mastercard Merchant Solutions) gave the sharpest provocation of the afternoon. [Recording Link]

She opened with a slide that got the audience uncomfortable very quickly. Less than 3% of Fortune 500 CPOs become CEOs. The table made the reason plain: CEO feeder roles own a P&L. CPOs typically don’t. Product is seen as a delivery function, not commercial leadership.

“If you don’t own the numbers, you don’t own the strategy. You’re just making suggestions.”

Her playbook had three parts. First: own the P&L. Not nominally - actually. Know your unit economics, your marginal costs, how your pricing is engineered. If you’re not in that conversation, you’re not in the strategy conversation.

Second: design for distribution. Channel strategy is product strategy. The distribution channel is often more important than the product itself - a point she attributed to Drucker and applied directly to the emerging reality of agentic commerce.

You can’t design a product and then force it into the sales channel as an afterthought.

Third: escape the duality trap. Stop treating Product Development and Product Proposition as two separate tracks. The “all-round product manager” owns the narrative, not just the roadmap.

“What are the tasks I am doing that are not going to help me be a great advisor to the CEO - and automate that away. So you can start thinking not about roadmaps, but about gross outcomes and real impacts.”

That last line is a mirror too, in its own way.

The Mirror

Jessica Hall (CPO, Just Eat Takeaway) closed the day. [Recording Link]

Her talk had the same structure as the day itself - it built to the thing it was always going to say.

The best concept of the day came from her: Human Glue.

The people in your organisation who exist to hold together a workflow that should not require them. The unwritten rule. The manual step. The person who “just knows” how to make it work.

“Simplify then automate was the way we used to think about automation of messy processes. Now if you automate a mess with AI, you just end up with an expensive AI mess.”

Her audit is simple: find the person on your team who is required to enable a workflow that should be self-serve. That’s not a resource problem. That’s a signal. The human is there because the process is broken, and the process is broken because no-one has been forced to fix it yet.

“Which ‘unwritten rule’ is currently acting as a tax on your team’s ability to scale at the speed of AI?”

She had a slide I hadn’t seen coming. “Creators to Curators.” Stop worshipping at the altar of the ‘feature.’ Apply your mirror to your actual problems. Don’t build the logic - curate the model that generates it. The shift from weeks to hours is on the other side of that mindset change, not on the other side of a tool decision.

JET holds 104 petabytes of data. 570 million events a day. At that scale, the old answer to a broken process was to throw headcount at it. That answer stopped working a while ago. The question she left the room with:

“Is your data foundation designed to provide answers, or is it just a pile of raw material that requires a plumber to navigate?”

And then, the closing slide. A silhouette walking toward light. Four words on a quote card that pulled the whole day together:

“AI isn’t just a tool for your product, it’s the high-definition mirror for your business. What it reveals is yours to fix.”

That was it. That was the whole day in one sentence.

The Thing Stopping You

The event opened with a slide: BUILD SOMETHING THAT DOESN’T EXIST.

Every speaker was addressing a different face of the same underlying problem.

Peiris on the debt you’re avoiding. Hall on the humans masking broken processes. Nutter on the loops that don’t teach. Kennedy on amplification as a mirror. Barkman on what leaning in structurally actually looks like. Parpou on the commercial outcomes product leaders keep handing to someone else.

The thing you’re walking away to build doesn’t exist yet.

But the thing stopping you from building it probably does. It’s just been invisible.

Until now.

Which of these talks made you uncomfortable? That’s probably the one worth acting on first.

If this landed for you, #87 (Before AI Can Help, UX Leaders Must Solve Operational Tech Debt) connects directly to Hall’s Human Glue argument.

I’d love if you subscribed — trying to build something useful for people working at the sharp end of product.

Subscribe now

This blog is going to be a little different.

I share a lot about what I’m working on with AI, and how you can use similar approaches, but I rarely show the full process I follow when I go deep down an AI rabbit hole.

I build a lot of agents, and creative writing agents are no different from the ones I use to create Jira stories.

With a busy job and a three-year-old, my free time is scarce.

If I want to keep producing blogs at the standard I aim for - and do it consistently - I need a proper system behind the scenes.

And - similar to how I run my AI workflows as a PM - I treat the workflow like a project, not the writing itself. The system handles the setup and structure, and I get to step in for the part I love: shaping, editing, and bringing the final piece to life.

So in this one, I’m going a bit meta.

This is the story of how I built a content creation ecosystem that transforms voice notes into published content - and how I tested four different approaches to find which one actually works.

Problem: Ideas in Your Head, No Time to Write

Tuesday afternoon. I’m installing a new shelf in the front room of my house, an arduous task as these are solid concrete walls from the 60s, while at the same time I’m trying to keep this shelf level, and a thought pops into my head.

“what If I used the prompt I used to create my DIY agent in my epic creation workflow - that would make a big improvement for the task tracking - this is genuinely useful”

“I should blog about this.”

Sunday evening rolls around. I finally have time to write. Open laptop. Stare at blank document. What was I so excited about on Tuesday? The clarity is gone. The energy is gone. The specific example I was thinking about?

Fuzzy at best.

I type three paragraphs. Delete two. They sound robotic. Nothing like the enthusiasm I had while holding a drill and mentally drafting the perfect post.

This happens constantly.

Ideas show up while you’re doing other things. Driving children to school. Fixing that kitchen shelf. Mid-standup when someone asks a question that sparks a realisation.

In those moments, you have context. You have emotion. You have the exact problem and solution crystal clear in your head.

But writing doesn’t happen then. Writing happens hours - or days - later, when you finally carve out time. By then, the idea excitement has faded. The specific details have blurred. You’re left trying to recapture lightning in a bottle, except the bottle is a Google Doc and lightning doesn’t cooperate.

Here’s what makes this particularly frustrating:

Time. Traditional writing is slow. I’ve spent 8-hour Sunday sessions on a single blog post (granted, my partner was away with my son, but still). That’s a full workday sacrificed to content creation, when I’d rather be with my family or friends or, honestly, just not staring at a screen.

Context switching. Every time you stop actual work to write about work, you break flow.

That problem you were deep in? Gone.

That solution you were building? Interrupted.

The cost is more than the writing time - it’s also the productivity lost getting back into what you were doing.

Energy loss. Ideas are exciting when they’re fresh.

That burst of “this could help so many people” is powerful. But by the time you sit down to write, it’s just... an idea.

The emotion that made it worth sharing has evaporated.

Perfectionism. When you’re typing, every sentence feels permanent.

You read it back. It’s not quite right.

Delete. Rewrite. Still not right. Delete again.

An hour later, you’ve got two paragraphs and a headache. The barrier to “good enough to publish” feels impossibly high.

Voice versus written. When you’re explaining something out loud, it flows.

You tell stories. You get animated about frustrations. You naturally emphasize what matters.

But when you type? Suddenly everything sounds formal. Stiff. Like you’re writing a report instead of helping a colleague.

The real cost isn’t the 8-hour writing sessions. It’s the ideas that never became content.

Every “I should blog about this” moment that died in your mental backlog because the gap between thinking something and publishing something felt too wide to cross.

The AI Solution: Voice → Agent Ecosystem → Published Content

Remember everything I just said about perfectionism preventing publishing? Yeah, about that.

I built this system in December. It’s now mid-February.

I’ve had these agents working brilliantly for two months, but I kept thinking, “The blog post about the system needs to be perfect before I publish any blogs using them.”

The system that solves perfectionism was held hostage by… perfectionism.

Classic.

Last weekend I finally made the changes I’d been overthinking. Yesterday I used those exact changes to start writing this blog. The irony is not lost on me.

So here’s the solution I’ve been building - and yes, it genuinely works, even if I’m proof that building the system doesn’t magically cure you of the problems it solves.

Instead of waiting for a perfect Sunday morning to sit down and write (which never comes), I talk through ideas when they’re fresh.

Voice notes while driving. Quick recordings after meetings. Rambling thoughts captured while they’re still exciting.

Then I let a three-agent ecosystem transform that raw thinking into (mostly) polished content.

Quick tip: Most smartphones have excellent built-in transcription. I’ve used both Samsung and OnePlus’ native recorder apps - both let you share transcripts as a txt file or shareable link. Send it to yourself on WhatsApp, open WhatsApp Web, and share it with your chosen AI tool. Simples.

Think of it like this: instead of one AI trying to do everything (which never quite works), I’ve got three specialised agents that hand off work to each other. Each one handles what it’s genuinely good at.

The Content Brainstormer processes your scattered thoughts.

The Research Enhancer finds supporting evidence when you need it.

The Style Replicator makes sure everything sounds like you, not like ChatGPT wrote it.

The key is understanding when to use which agent, and how they fit together.

Agent #1: Content Brainstormer

This is your entry point - the agent that catches those shower thoughts before they disappear.

You throw your mess at it, your “word vomit”. Voice note transcriptions. Meeting recordings. That LinkedIn comment thread where you accidentally wrote three paragraphs explaining your position. Email threads where you’ve already explained the concept twice. Slack conversations where you solved someone’s problem in real-time. Even just bullet points hastily typed on your phone.

The Brainstormer’s job is to find the content hiding in that mess. It asks clarifying questions. “You mentioned this frustrated you - what specifically about it?” “You said this saved you time - how much?” It identifies the insights you don’t realise you’ve already articulated. It structures your scattered thoughts into something that could become a post.

Most importantly, it tells you where to go next.

Sometimes your idea is ready for the Style Replicator - you’ve got the full story, you just need it polished. Other times you need the Research Enhancer first - you’ve got an opinion but you’d benefit from data, examples, or industry context to back it up.

Agent #2: Research Enhancer

This is your middle specialist, and you don’t always need it.

Skip this agent entirely if you’re writing personal stories, quick opinions, or time-sensitive hot takes.

Your LinkedIn post about a frustrating meeting this morning? Doesn’t need research.

Your reflection on a career mistake? That’s pure personal experience.

But when you’re tackling technical topics, thought leadership pieces, or how-to guides, this agent is valuable. It runs a structured research workflow: finding credible sources, gathering relevant data, discovering case studies, identifying industry best practices. It can suggest LinkedIn optimisation insights (what similar posts performed well, what hooks work for your topic). It helps with implementation guidance when you’re teaching something complex.

The Research Enhancer understands its job isn’t to write your content. It’s to give you ammunition. Here are five relevant examples. Here’s recent data on this topic. Here’s how other people have explained this concept. Here’s what’s currently being discussed about this on LinkedIn.

For technical articles: If you’re writing about code or libraries, use Claude Code Marketplace plugins. Serena (semantic code analysis) can search Context7 (library documentation lookup) for targeted pattern matching. The workflow: Serena first understands what you’re trying to achieve, then searches Context7 based on that understanding.

This is more powerful and uses less context than Claude’s explore agent. Prompt example: “Use Serena to analyse the Jira API patterns in this codebase and search Context7 for Atlassian API best practices.” This gives your Research Enhancer accurate, up-to-date technical context instead of potentially outdated training data.

Then it hands everything over to the Style Replicator with your original voice notes still intact.

Agent #3: Style Replicator

This is where your content actually becomes yours.

The Style Replicator has one job: take everything from the previous agents (or just from the Brainstormer if you skipped research) and transform it into your authentic voice.

Not “professional blog voice.” Not “how AI thinks you should write.”

Your actual voice - the way you explain things to colleagues, the tangents you go on that actually make the point clearer, the specific frustrations that make your content relatable.

It does this by learning from your existing content. In my case, it’s analysing 95+ blog posts I’ve already written. It learns how I structure explanations. How I use examples. What phrases I actually use versus ones I’d never say. It adapts to different platforms too - LinkedIn posts need to work on mobile with that 1300 character sweet spot, while Substack articles can breathe and go deeper.

Fair warning: Building this corpus was painful. Substack doesn’t have good API hook-ins, so I had to export every single blog post as a PDF, then convert all of them to markdown. Same for LinkedIn posts - I had links from my weekly tips metrics tracking back in 2024, but still needed to convert each one into a format Claude could use. It’s a once-off setup, but it’s not trivial. The payoff is a Style Replicator that genuinely knows your voice, but you’re looking at a few hours of export-convert-organise work to build your corpus.

The Style Replicator also handles the unglamorous but critical work of removing “AI-isms.” Those phrases that immediately signal ChatGPT wrote this: “in today’s rapidly evolving landscape” or “it’s worth noting that” or “let’s dive in.” It strips those out because they’re not how real humans write.

Most importantly, it preserves the emotion from your voice notes. That excitement when you discovered something useful? That frustration that made you want to write about the problem in the first place? That stays in the final content, because that’s what makes people care.

Share

How They Work Together

The workflow is deliberately flexible, because not every piece of content needs the same treatment.

Quick personal post? Brainstormer → Style Replicator. Done in 20 minutes.

Technical deep-dive? Brainstormer → Research Enhancer → Style Replicator. Takes longer, but you get a comprehensive piece with supporting evidence and your authentic voice.

The key insight is this: by breaking content creation into specialised phases, each agent can focus on what it’s genuinely good at. The Brainstormer doesn’t try to research. The Research Enhancer doesn’t try to write in your voice. The Style Replicator doesn’t try to generate ideas from scratch.

And you? You just talk. Capture the idea when it’s fresh. Let the ecosystem handle the transformation from “interesting thought” to “published content.”

Testing What Actually Works

Building the system wasn’t enough. I’m a product manager - I needed data. Which approach produces the most authentic content? Which one is fastest? Where’s the sweet spot between efficiency and quality?

So in December 2025, I ran an experiment. Same topic, four different paths, see what happens.

Call it thoroughness. Call it perfectionism. Call it procrastination disguised as rigour. Whatever it was, I’m glad I did it.

Path 1: Popular Styles (Following the Crowd)

The hypothesis: research what works, then write like that.

I started by researching optimal blog formats. What structures drive engagement? What hooks work on LinkedIn? What do the top performers do?

Turns out, there’s a pattern. Problem → Solution → Implementation → Results. That’s the formula. Nielsen Norman Group says 79% of readers scan content. Sprout Social shows the first 200 characters determine engagement. The data’s all there.

So I followed it. Researched the best practices, found the proven patterns, structured my content accordingly.

The result? Solid content. Professional. Well-structured. Completely generic.

See that Nielsen Norman Group percentage line above? That’s exactly the kind of thing I was trying to avoid. Yes, citing engagement statistics probably boosts credibility or whatever. But it’s not me. This blog was never about becoming the most popular blogger out there - it’s about getting my ideas across in a way that feels comfortable. That’s why Path 2 won.

Path 2: Double Style (The Winner)

This was the experiment within the experiment. What if voice pattern analysis happened twice - once at the start, once at the end?

Voice First: Before writing anything, I analysed my entire corpus. All 95+ blog posts. Built a comprehensive voice guide - 40KB of patterns, turns of phrase, authenticity markers. Documented how I actually write when I’m not thinking about writing.

Draft in the Middle: With that voice guide loaded in my head (and in the AI context), I created the content. The voice patterns were already steering the first draft.

Voice Last: Then I ran everything through the Style Replicator again. One final pass to remove any AI-isms that crept in, polish the rough edges, make sure every sentence sounds like me.

Double pass. Voice First, Voice Last.

The result? Authenticity scores of 9.0+. Consistently.

This is the approach that won. This is what I use now. And yes - this very blog post you’re reading? Created with Path 2. Meta as hell, but it proves the point.

Path 3: Standard (The Baseline)

The traditional research-enhanced workflow. Brainstorm → Research → Style.

Make claims, then validate them. Add sources. Check facts. Make sure nothing I’m saying is provably wrong.

This is what most people think of when they think “AI-assisted content creation.” Write something, have AI help polish it and add research depth.

Research quality score: 8.7/10. Twelve credible sources. Every major claim validated. Professional, thorough, defensible.

The result? Solid. Reliable. The safe choice.

If you need research-backed content and you’re not as neurotic as I am about voice consistency, this path works fine.

It’s faster than Path 2 (no upfront voice analysis - which is tricky and slow when you are trying to do this on the Claude code pro plan), and it gives you the research credibility that some topics need.

Path 4: Research First (The Validator)

What if you researched before writing anything? Not to validate claims - to validate whether the topic is even worth pursuing.

This path starts with deep discovery research. Market viability scoring. Audience interest validation. Competitive landscape analysis. You’re not building content yet. You’re deciding if you should.

For this topic (voice-to-content workflows), Path 4 gave it a 9.2/10 viability score. High confidence to proceed. Evidence of genuine gaps in the market. Proof that people want this information.

The result? Strategic confidence.

You don’t waste time creating content nobody wants. You validate demand first, then invest in creation.

This is the path for big bets. Flagship content. Things you’re going to spend serious time on. You want to know it’s worth it before you start.

What the Experiment Taught Me

Four paths. Same topic. Different results.

Path 1 gave me professional content that sounded like everyone else.

Path 2 gave me authentic content that sounds like me - at scale.

Path 3 gave me credible, research-backed content with solid voice.

Path 4 gave me confidence I’m solving a real problem people actually have.

And to be fair - I likely will still use all four paths. Just for different purposes.

• Quick LinkedIn post where I know the topic resonates? Path 3. Fast and credible.

• Important blog post where voice authenticity matters? Path 2. Every time.

• New topic where I’m not sure there’s an audience? Path 4 first, then one of the others.

• Following best practices for procedural content? Path 1 works fine.

The experiment wasn’t about finding “the one true way.” It was about understanding the trade-offs. Knowing which tool to use when.

Product management brain strikes again.

Behind the Curtain: How This Section Was Scored

In keeping with the tone of the blog - I’m going to show you the actual authenticity assessment that was generated for this first part. This is the scoring process that happened in real-time as I created this blog using Path 2 (Double Style).

Transparency matters. If I’m claiming these approaches produce measurable authenticity scores, you should see what that actually looks like.

Authenticity Self-Assessment: 9.0/10

What worked:

• Conversational narrative flow (no bullets)

• British English maintained (optimisation, analysed)

• Space-hyphen-space used throughout (grammatically incorrect but authentic to John’s voice)

• Personal voice strong (”Call it perfectionism...”)

• Meta moment included naturally (”this very blog post...”)

• Explains the “why” of experimentation (PM brain, wanting data)

• Practical tone maintained (trade-offs vs absolutes)

AI-isms removed:

• “Here’s the thing”

• “It’s important to note”

• “In conclusion”

• “Furthermore/moreover”

• Generic transitions replaced with conversational connectors

Voice accuracy check:

• Personal vulnerability: “Call it procrastination disguised as rigour”

• Practical framing: “knowing which tool to use when”

• Meta-commentary: “Product management brain strikes again”

• Conversational asides: “Call it X. Call it Y.”

• Acknowledges all paths have value (not absolute thinking)

That’s the actual output. Not polished for publication. Just the raw assessment of whether this section sounds like me.

And yes - including this assessment in the blog itself drops the authenticity score slightly (adding meta-layers always does). But it proves the point better than any explanation could.

What’s Next

So I’ve shown you the problem (ideas dying in your head), the solution (three-agent ecosystem), and the validation (four experimental approaches, with Path 2 winning on authenticity).

But what I haven’t shown you yet is how this actually works in practice (unless you count this blog of course)

What does the workflow look like when you’re creating a LinkedIn post in 40 minutes? What about a full blog post in under 3 hours? What tools do you actually need? Where do things break? What gotchas did I discover the hard way?

That’s coming. Real examples, step-by-step workflows, time breakdowns, the stuff that actually matters when you’re trying to replicate this yourself.

For now, you know the system exists. You know it was tested. You know which approach won.

Next time, I’ll show you how to use it.

I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.

Subscribe now

📖 Updated January 23, 2026 (Reflecting Claude Code 2.1.17)

This post was originally published in October 2025 during the Claude Code 2.0.20 release when Skills were first introduced. Since then, the platform has evolved relentlessly through foundational features in 2.0.0 to the current 2.1.17 era. The most significant shift occurred in version 2.1.3, which fundamentally merged Skills and Commands into a unified concept.

The content below has been updated to reflect the current state of infrastructure management, incorporating lessons learned from managing 340+ infrastructure files and navigating several major breaking changes.

A quick note before we dive in

I haven’t been writing as much recently, and there’s a good reason. Over the past three months, my entire AI and PM workflow has been completely upended.

Anthropic has been absolutely blasting out new functionality - plugins, marketplaces, skills - each one landing before I’d fully processed the last.

Aside from these releases, I’ve been deep in the trenches exploring Claude Code functionality, not just using it, but really understanding how it works, what’s possible, and what it means for how we build and collaborate with AI.

Skills turned out to be the Aha moment for me. It might not be the last thing Anthropic release around marketplaces, but it was this release that has allowed it all to finally click with me and my existing processes.

I’m just coming out the other end now with a much clearer picture of how these pieces fit together, and more importantly, how to help my team and wider division adopt these new ways of working in the coming months.

This post is just me documenting that clarity while it’s fresh.

I’m currently in the middle of writing a blog series on Claude Code tips, tricks, and best practices, and this first post isn’t the gentle introduction I originally planned.

I was going to ease in with straightforward topics like context management and useful commands, then Skills launched last week, and it looked like the missing piece I was waiting for, so I spent a good portion of my last week testing and rebuilding different parts of my workflows to understand these new systems.

When a fundamental shift happens, you pivot.

Consider this the “why does any of this matter” post before we get to the “here’s how to use /compact” posts. What follows is my current understanding based on the documentation, early testing, and a lot of trial and error.

I’m documenting what I’m learning in real-time, backed by my own testing with my different agents, commands and projects in Claude Code.

This post walks through what I learned about four core types of Claude Code extensibility and when to use each one. (There are others like hooks and MCP servers, but these four are where I started.)

The Mental Model: Four Core Types

Claude Code supports multiple extensibility types (skills, subagents, commands, plugins, hooks, MCP servers, and more). This post focuses on four that work together as a cohesive system. Each serves a specific purpose, and understanding when to use each is critical.

Here’s a simple decision tree:

• “I want Claude to remember X automatically” → Skill

• “I want to automate Y workflow step-by-step” → Subagent

• “I use subagent Z frequently and want a shortcut” → Command

• “I want to share my setup with others” → Plugin (bundle all three)

Skills: A Discovery Journey

Skills are auto-invoked context providers. Claude automatically loads them based on description matching with the conversation context.

Location hierarchy:

• Personal: ~/.claude/skills/ - Your own preferences and context

• Project: .claude/skills/ - Project-specific information

• Shared: Template skills that can be reused across projects

I started by creating three skills to test this system:

1. Personal user manual (my work preferences and communication style) (https://www.youngleaders.tech/p/why-you-should-have-a-personal-user-manual)

   1. I’m treating this like custom instructions on ChatGPT - What I like, who I am, what are my working styles, goals etc.

2. Test Project stakeholders (product lead and UX research lead context)

   1. Current use case for this one is for using when creating user stories for stakeholder personas. This skill would be hold key information about the persona tied to the stakeholder and it would be triggered when I work on a user story with the matching trigger text or persona name

3. Stakeholder template (a meta-skill for creating other stakeholder skills)

   1. I’m in a platform team, I have many stakeholder personas to support!

The critical success factor at this step was also my first discovery - description quality directly determines auto-invocation accuracy.

Generic descriptions failed completely.

But when I structured descriptions with a WHEN + WHEN NOT pattern, the skills were being invoked each time.

Example that works:

description: Stakeholder context for Test Project when discussing product features,
UX research, or stakeholder interviews. Auto-invoke when user mentions Test Project,
product lead, or UX research. Do NOT load for general stakeholder discussions
unrelated to Test Project.

Example that doesn’t work:

description: Provides information about stakeholders

Key success factors for descriptions:

The difference is specificity and boundaries. You need to tell Claude:

• What the skill contains

• When to load it

• When NOT to load it

Putting the above at #1, here are the other findings:

1. WHEN + WHEN NOT pattern: Explicit boundaries prevent false positives

2. Possessive pronouns: “HIS/HER/THEIR work”, “HIS/HER/THEIR messages” scoped my personal skills perfectly

3. Multi-skill coordination: Claude successfully loads complementary skills together

4. Template meta-pattern: Template skills can provide guidance for creating other skills

Real-World Example: Personal User Manual

This is the first skill I created and deployed - and it was based on a prior blog of mine:

Here’s the skill description:

description: Personal work preferences and communication style for John Conneely. Auto-invoke when drafting HIS emails, Slack messages, or internal updates; planning HIS work or tasks; optimising HIS productivity workflows; or discussing HIS collaboration approach. Auto-invoke when user requests “help me write”, “draft an email”, “create a message”, “plan my work”, or “write internally”. Do NOT load for external blog posts, customer-facing communications, or public documentation unless John explicitly requests.

What it contains:

• My preferred collaboration methods and communication channels

• How I like to give and receive feedback

• My approach to documentation and technical decisions

• Internal workflow preferences

This skill now automatically provides context whenever Claude assists me with my personal work, without me needing to repeat these preferences in every conversation. I’ve only had this enabled for a couple of days, so I can’t tell for sure how much of a difference this is going to make until I use it on a new project with no context.

Here’s a test though to show you the difference, of me asking Claude to help me create a slack message to share with the team about this blog. It’s pretty clear to me which one is written by an AI in these two examples, and I am a proponent of getting my points across quickly, which is clearly evident in the second example.

First example, with skill file removed

Personal skill file added back in

Certainly looks like a big improvement to me. Moving on..

Installing Skills from the Marketplace

Since I’ve been building and sharing agents for quite some time now, the most common question I get is: “How do I actually use these in my own Claude Code setup?”

The answer before plugins/marketplaces were released:

1. Clone my repo and run the install script

   1. But only if I am not worried about all the AI slop and have made the repo public

   2. And only if it doesn’t have any sensitive information

   3. And only if the agent was built after the version of the agent builder that included installer script validations

   4. And only if I remembered to trigger that validation agent when creating the agent initially because I didn’t have any commands

   5. And only after the validation agent was refactored to <500 lines of instructions from 1000+, fixing a load of the missed installer validations

2. Now rinse and repeat for 20/30 other agents

The answer in October 2025 (which still works now):

1. Clone the marketplace repository

2. Find the plugin that contains the skill you want

3. Run the plugin install script.

For the above, simply swap out skill with agent, command, hook or template and the instructions remain the same.

Luckily for you, I already have published my skills toolkit, which includes the skills toolkit that you can see in the above screenshots. Here’s how you can get that and install it yourself.

# Clone the marketplace
git clone https://github.com/YoungLeadersDotTech/young-leaders-tech-marketplace.git

# Navigate to the plugin you want
cd young-leaders-tech-marketplace/plugins/skills-toolkit

# Run the install script
./install.sh

Now that I have this working, I also plan on adding some other useful agents to this marketplace (like my agent builder suite)

This install script automatically:

• Detects your Claude Code configuration directory

• Copies agents to .claude/agents/

• Copies commands to .claude/commands/

• Copies skill templates to .claude/skills/shared/

• Verifies everything installed correctly

No separate repos needed.

Everything is bundled in the marketplace. You don’t need access to multiple repositories - just clone the marketplace and you’re done.

If you’re rolling skills out to a team:

• Share the marketplace URL with your team

• Document which plugins solve which problems

• Consider forking the marketplace for internal customisation

• Use git to keep everyone’s installations in sync

Updates

To update a plugin, pull the latest marketplace changes and re-run the install script. The script overwrites existing files, so you get the latest version.

Is it Time to Refactor Agents with Skills?

Subagents are explicit workflow orchestrators. You invoke them by typing @agent-name, keywords or through the Task tool. They guide multi-step processes.

As I explained above, as part of the learnings and testing in this whole process, I built two subagents:

1. skill-creator-agent - An interactive workflow for creating new skills

2. skill-validator-agent - A comprehensive validation checklist for skills

But the same problem I have had all along followed me here

The problem I am talking about is one that I have with a lot of my existing agent files. In an effort to keep instruction files minimal, I have implemented template re-usable instructions for most of my agents to refer to in their agent instructions, and they are quite difficult to maintain across different agent suites and repos.

From what I can tell at this early stage is that skills seems to fill in this gap, and make this a little less painful.

Here is an example, using the agents you can find on my marketplace.

My First Pass

(Without skills, as I didn’t have an agent to create them yet)

I ended with 803 lines for the skill-creator-agent.

I was pretty happy with the functionality. Comprehensive workflows, detailed instructions, extensive validation. Of course, I knew it was way over the advised size of agent instructions (3/400 lines max), but I was going to get them evaluated, so it wasn’t a problem yet.

Next, I asked my eval committee to review it. (Eval alumni are coming soon to the marketplace)

Eval committee score: 62/100

Primary feedback: “Too verbose. Redundant structure. Difficult to maintain.”

That stung. But they were right.

I had:

• 5 duplicate TODO structures across the subagent

• A 130-line misaligned template section that should have been a separate file

• Consolidated checklists that repeated themselves

• Over-explained instructions that could be streamlined

My Second Pass

I spent the next iteration refactoring both subagents based on the feedback:

Before:

• skill-creator-agent: 803 lines

• skill-validator-agent: 698 lines

• Total: 1,285 lines

After:

• skill-creator-agent: 281 lines (65% reduction)

• skill-validator-agent: 306 lines (56% reduction)

• Total: 587 lines (54% reduction)

Zero functionality lost.

Every capability remained intact.

So, what changed?

• Removed duplicate TODO structures (5 instances → 1 reusable pattern)

• Extracted the misaligned template to a separate skill file (This is where I’m seeing the big improvement to agent performance by the way)

• Consolidated redundant validation checklists

• Streamlined instruction language without losing clarity

• Improved maintainability through DRY principles

Post-refactoring eval: Estimated 82-85/100

So the learning that was reinforced from this is that More lines ≠ better instructions.

Subagents need to be maintainable, not comprehensive. Claude is smart enough to work with concise, well-structured guidance.

Skills enables this even further.

Subagent Analyses, Main Claude Executes

This is an architectural pattern I validated - a hybrid approach for subagent-command interactions.

How it works:

• Subagent uses Read, Grep, Glob, TodoWrite (analysis tools only)

• Subagent analyses context and creates comprehensive plan

• Main Claude executes Write, Edit, Bash (modification tools)

• This preserves tool access control while enabling workflow automation

Why this matters:

Slash Commands can invoke subagents for planning, then Main Claude handles execution. This pattern gives you the best of both worlds - structured workflows with full tool access.

But wait, what are slash commands?

Slash Commands are Shortcuts to Workflows

Commands are user-initiated shortcuts. You type /command to trigger them.

They are essentially prompts that can be saved per project or globally. These are powerful ways to ensure changes you make are actually working, as a tiny change in your prompt from one session to the next can have dramatically different outputs.

You can also direct the command towards the skill file, so you don’t have to worry about it being triggered by the keywords.

What do they look like? Well, if you install the above plugin on my marketplace, you can test this out yourself quite quickly.

I created three commands as part of my digging this weekend using my command subagent (also coming soon to the marketplace)

• /create-skill - Invokes skill-creator-agent for interactive skill creation

• /validate-skill - Invokes skill-validator-agent for comprehensive validation

• /list-skills - Simple bash script to show all available skills

Most commands either invoke subagents (workflow shortcuts) or run simple bash scripts (utility shortcuts). They get saved to .claude/commands/ in your project or personal directory

Commands are the fastest way to start frequently-used workflows. Instead of typing “Can you help me create a skill?” or “@skill-creator-agent”, I just type /create-skill and the workflow starts immediately.

Can Plugins Help with Scalable Agent & Tool Distribution?

Well, yes, I think that is their main purpose.

Plugins are bundled packages of skills, subagents, and commands distributed as cohesive units.

As you may have surmised by now, I have shipped my first plugin - The Skills Toolkit - to the Young Leaders in Tech Marketplace.

What is in it?

• 2 intelligent subagents (skill-creator-agent, skill-validator-agent)

• 3 slash commands (/create-skill, /validate-skill, /list-skills)

• 4 professional skill templates (stakeholder, ground truth, product context, initiative overview)

• Complete installation script with automatic setup

• Full documentation and troubleshooting guides

The install script that comes with the plugin detects your Claude Code directory and copies everything to the right locations. No manual file management, no missing dependencies.

Plugins may solve the distribution problem.

Instead of sharing scattered markdown files or with complex install scripts on scattered repos, you now get a complete package with versioning, documentation, and automated installation. Users don’t need to understand your directory structure - they just run the install script.

What’s next

I’m gradually adding more plugins to the marketplace as I identify patterns worth sharing. The marketplace is young, but it’s where I’m investing time because I see the potential for community-driven extensibility. I also have 40 or 50 agents at this point that people may find useful, and this seems to be a great way to share.

Key Takeaways

After a week of building and testing (along with some already known takeaways), here’s what I think I know:

1. Description engineering is critical for skills

• Use WHEN + WHEN NOT pattern for explicit boundaries

• Possessive pronouns (”HIS/HER/THEIR work”) prevent contamination

• Test your descriptions - generic descriptions fail

2. Multi-skill coordination works

• Claude successfully loads complementary skills together

• Personal + Project skills can coexist without conflicts

• Template meta-skills provide guidance for creating other skills

3. Subagents should be concise, not comprehensive

• First draft: 803 lines, eval score 62/100

• Refactored: 281 lines, eval score 82-85/100

• Zero functionality lost in refactoring

4. The hybrid pattern is effective

• Subagents analyse using Read/Grep/Glob/TodoWrite

• Main Claude executes using Write/Edit/Bash

• Preserves security boundaries while enabling automation

5. Commands are workflow shortcuts

• Many commands invoke subagents or run bash scripts

• Type /command instead of describing what you want

• Faster than typing subagent names or explaining workflows

The Learning Continues

This is what I know as of today (21st of October). I’ve validated these patterns through some small testing, but I’m still learning.

The Young Leaders Tech Marketplace is my experiment in sharing what works for me and might work for you.

The Skills Toolkit plugin is just the first - It’s not comprehensive, it’s not perfect, but it’s a real working set of agents in a plugin that you can use today to create your own skills.

I’ll be following this post soon with more Claude tips and tricks, but before that I need some help.

Things I’m still figuring out:

• Best practices for team/company-wide skill management

• Performance implications of many auto-invoked skills

• How skills interact with other Claude Code features

• What makes a plugin worth publishing vs keeping internal

If you’ve been experimenting with Claude Code extensibility, I’d love to hear what you’ve learned.

What patterns are working for you?

Where are you getting stuck?

Can you help me with any of the above?

Subscribe now

I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.

Here are some other blogs you may find interesting

Someone recently asked me if entry-level PM roles are disappearing. It’s a fair question.

The truth is, they’ve always been rare.

Product management has never had the same volume of entry-level roles as engineering or design. That hasn’t changed. What has changed is how people break in.

These days, the most reliable path is lateral: start in a stakeholder- or customer-facing role within a company that already has a well-established product org, then work your way in from there.

That’s how I got in.

Internal networking works.

Practising product methods in your current scope (even when it’s not asked of you) works.

And telling every PM who'll listen that you want to move into product?

That works best of all.

Even in tough markets, companies with solid PM structures don’t simply abandon them. If you can demonstrate leadership and product sense in your current role, you might actually be the best candidate - more cost-effective, already onboarded, and faster to ramp than an external hire.

AI can help you simulate some product work, but it can’t teach you product sense for your company. That only comes from doing the work, close to the customer.

What is Product Sense?

It’s the ability to understand what makes a product valuable, usable, and feasible—and being able to apply that lens within your specific context. It’s part customer empathy, part business acumen, part intuition. You notice friction points. You ask better questions. You sense when a feature feels off before the data catches up. And most importantly, you learn how to prioritise not just what could be built—but what should be built.

Why Adjacent Roles Are a Goldmine

If you're in support, implementation, or customer success, you’re already closer to product than you think. These roles offer an underrated advantage: they immerse you in real customer pain, over and over again.

I’ve mentored folks who broke into PM roles without CS degrees or MBAs.

The common thread? They proactively embedded themselves in product work. Whether by documenting themes in support tickets, mapping workflows, or identifying friction points in onboarding, they added value and made it visible.

At Toast, I advised a support team member to run lightweight discovery on recurring customer issues. They started grouping themes, sharing findings with PMs, using internal templates like opportunity trees and AI to sharpen the output. That kind of initiative gets noticed.

You don’t need permission to think like a PM. You need curiosity, a bias for action, and a way to make your thinking visible.

Support roles offer incredible variety. They give you exposure to the messiness of real operations - a mix of edge cases, system gaps, and unfiltered customer frustration. That context is powerful. The key is shifting your focus from output (solving one-off problems) to outcomes (solving them at scale). That’s when people start to take notice.

And while some roles may sound similar to product - like design or business analysis - they often follow different tracks. I’ve had to be honest with mentees: design roles today are highly competitive, increasingly affected by AI, and require a depth of craft that takes years to build. Product is a different path, and support can be a far better stepping stone.

The Missing Skill is Often Discovery

Discovery is where a lot of new PMs struggle - and for good reason. Many people enter product from roles that never required it. In many companies (including almost every company I have worked at), product owners were simply retitled as PMs without ever being intensively trained on discovery. That leads to an execution-first mindset (explained in more detail here), where building fast is prioritised over understanding what’s worth building at all.

That’s why over the past few years I have started creating and sharing these discovery templates: opportunity trees, PRD scaffolds, structured problem definitions, and how to use Atlassian products to boost your outputs. They’re not just for PMs. They’re for anyone trying to do better discovery, even unofficially.

Sometimes the cost of skipping discovery isn’t obvious until months or years later. Maybe a compliance need was missed. Maybe a workflow was poorly scoped. These things compound - and future teams pay the price.

If you document clearly and structure your learnings, you’re not just helping now - you’re protecting your team in the long run.

If you work in support or ops, you already have access to high-signal pain points. Document them. Group them. Tie them to user outcomes. That kind of thinking doesn’t just help the product team - it helps you become more effective in your own role.

How to Be a PM Before You’re a PM

One of the best ways to prepare for a product role is to start behaving like a PM in the role you already have. Don’t be afraid you might overstep your mark or impede on the product team, you will be contributing structured insights, solving team-wide problems, and making your thinking visible. This kind of context in an AI landscape is incredibly important.

Start with discovery. Look at repeated customer pain points. Group them into themes. Use frameworks like Reach x Impact (check the notes section of my Miro template linked above to prioritise them. Visualise them in Miro or track them in Jira. You can even build a mini discovery board for yourself - call it the "Becoming a PM" board. It helps you define what gaps you need to close to move into product.

Copy my board. Then start small - documenting your customer problems and workflows.

Support is an excellent place to practice this. Every support interaction is a mini signal. When grouped and structured, they tell a story about what’s broken and what could be fixed. By sharing these stories with PMs, you're not just shadowing. You're shaping.

Even if you never make the move into product, these skills will make you better in your current role. You’ll be more strategic, more focused, and more respected across teams.

Don't Wait for the Role to Come to You.

Roles don’t always need to exist before you grow into them. I’ve seen this first-hand. If you’re solving real problems that are not just in your own lane, but across teams - and you make that work visible, opportunities tend to reshape around you.

Maybe instead of hiring one senior PM, a team hires two associates because that’s what the work calls for. Maybe you create such a useful structure for your team that leadership rethinks how support and product collaborate entirely. Roles aren’t fixed - they’re just stories we tell about where someone fits. Change the story, and you can change the role.

But if you never speak up? No one will know.

Be vocal about what you want. That’s product work at its core - clear communication, stakeholder alignment, and driving outcomes. If you haven’t told anyone in the product org that you want to move into product, how can they consider you when the moment arrives?

Telling your manager is a good start - but remember, your career is your responsibility. In modern tech, managers are stretched thin. They may not fully grasp the relevance or value of the PM-style work you're doing on the side, and they likely can’t (or won’t) advocate for you in rooms you’re not in.

Sometimes, your manager may even see this extra work as a distraction - especially if you're a strong contributor in support. It’s natural for team leads to prioritise team performance over individual ambition.

This is where you’ll need to rely on your own judgment. If your manager is supportive, go all in - as long as your core work doesn't slip. But if they’re hesitant, find subtle ways to build credibility with the product team directly. The key is to keep moving forward while being pragmatic about the context you’re in.

Why AI Is Non-Negotiable Now

Almost every task a product manager does can be enhanced by AI. User story drafting, PRD writing, idea validation, competitor research, stakeholder communication, journey mapping - AI can support all of it.

But only if you learn how to prompt it well.

My approach is simple: use AI wherever you find friction. Too many thoughts in your head? Ask ChatGPT to help structure them. Unclear on a problem space? Feed your notes into Gemini and ask what’s missing. Need examples of KPIs or OKRs? Ask for five variations.

Then iterate.

AI can help you get unblocked, polish your thinking, or simply accelerate tedious steps. But it’s only powerful if you give it structure. I spend a lot of time feeding it labelled inputs and real content from my different projects. Then I let it react, reframe, and spark better outputs.

I encourage everyone I mentor to get a personal ChatGPT subscription. Not because it makes you a product manager - but because it erases the friction between you and the skills you need to learn.

Want to write a PRD? Ask ChatGPT to help based on a flow you draw in Miro.

Want to draft OKRs? Feed in your goal and let it propose options.

Want to understand how Reach x Impact works? Ask it to explain, then ask again for five examples.

AI doesn’t (and shouldn’t) replace your thinking, but it does supercharge it. Especially if you’re coming from an adjacent background, it closes the gap between your intent and your execution.

You Don’t Need a Title to Build a Track Record

You can start building your product portfolio now. No permission needed.

Spin up your own Jira instance. Run a discovery project on something in your current team. Document a pattern you’ve seen in support tickets and outline potential solutions. Share it internally. Build visibility.

I’ve seen people do this and get tapped for internal PM roles without ever applying. Why? Because they were already doing the job - just unofficially.

This isn’t theoretical work. It’s practice. And practice builds trust.

Closing Thought

If you’ve made it this far, you’re probably wondering where to start. I’ve included a curated list of resources at the bottom - roughly in priority order. These guides, templates, and examples reflect how real product managers work, and they’re all easily adoptable by anyone ready to step into that mindset.

Breaking into product has always required initiative. It’s not a career that hands out clear ladders or neat checklists. But if you’re in an adjacent role, are curious, and are willing to learn by doing - the path is still there.

You don’t need a PM title to start doing product work. You just need to start.

Subscribe now

Add a design system to the knowledge of the tool you’re building in.

It significantly improves the quality of the outputs. I’ve seen this first-hand after doing it myself.

When I was told this, I didn’t actually know how to create a design system (or what even goes into one).

I'm building something based on a spreadsheet I use for capacity planning, so I used the prompt below to help generate one:

I'm creating an XYZ app in <lovable/bolt/v0/replit> that consists of all the functionality that can be found in the attached spreadsheet, and I'd like to create a design system to help me build the app.

Can you keep asking me questions about the app I'm trying to build that will help inform you of the design system?

Ask me questions in such a manner so you can create a low fidelity system first, I'll revise your low fidelity, then ask me more questions to get to what you consider medium fidelity, I'll revise again, and then continue asking questions until you have a high fidelity design system.

Simply answer the questions it asks you, and you’ll get great stuff to use for building.

Below is the very first response I got - the questions that helped generate the low-fidelity version of the design system.

Is this accurate for what a design system actually is?

Can you let me know?

Using AI is great, but this is one of the things I often debate with myself -how much trust are we putting in tools like this, assuming what they’re giving us is “truth”?

That’s a debate for another day.

In this case, I’m not really looking for the truth.

I’m looking for something that helps me build better stuff - and these steps definitely help.

Subscribe now

For all my other AI posts, click below

https://www.youngleaders.tech/t/ai

That’s the question I explored in a recent talk I gave at the Dublin UX meetup, now available as a re-recorded video podcast episode here and on YouTube (or any of your podcast listening locations)In this talk, I go deeper than the usual discussion around UX buttons, spacing and visual polish. Instead, I trace the broader experience - across internal tools, invisible workflows, and the systems that support product development.

The central idea: Good UX starts long before a user clicks a button.

You’ll get some context on my own path - from civil engineering to customer support, and eventually to platform product management. I talk about where I’ve seen UX misunderstood or ignored, and how I’ve learned to practice UX in some of the least expected places.

Why this talk, and why now?

Historically, UX was treated as a design domain. If you didn’t work in Figma or touch the product UI, you most likely weren’t “doing UX”, or being considered to “do UX” even if you were.

With the introduction of AI and the User experience often associated with it (a chat window), I think we’re past that now - or at least, we should be.

This talk makes the case that

Platform PMs, internal tooling teams, ops leads - anyone shaping how work gets done - is also shaping UX.

Whether you’re designing a flow for your customers or a Slack automation for your team, you’re creating an experience. That deserves the same thoughtfulness we give to screens and user journeys.

Inside the talk

The talk is broken into three parts:

1. Why UX Is Bigger Than You Think

   I kick off by challenging the traditional view of UX as something you “see.” Like many PMs, I started out thinking good UX meant polished interfaces. But through customer support and platform work, I learned that real UX lives in infrastructure, systems and processes - often in places no one’s looking.

2. UX in the Unseen Places

   This section covers what happens behind the curtain: the messy Jira workflows, duct-taped internal tools, undocumented handovers. I show how internal users (like sales, support and ops) suffer from poor UX - and how fixing their experience makes the entire product better.

3. Solving the Right Problems the Right Way

   I end by walking through real-world examples - some good, some terrible. A toddler puzzle that teaches the danger of poor feedback loops. An ATM disabled for check lodgements just because it’s out of cash. And a beloved pair of headphones whose invisible UX failures drive me mad.

Through these chapters and the stories within, I explain how to build up a UX mindset, not just for users - but for your team, your process, and your product’s architecture.

NOTE: If you just want the slides, they can be found here.

If you’re in internal product, platform, or ops…

This talk is especially for you.

If you’ve ever been told “UX isn’t part of your job” because you don’t work on the customer-facing side of the product, this talk is my case that you are doing UX - and it matters.

I share the exact templates and processes I’ve used at Toast, from building AI-friendly Miro boards, to mapping internal user journeys, to designing ways of working that reduce burnout and bottlenecks. If you’re curious, check out the QR code in the video or search the blog for the template numbers from the slides.

“So start looking for UX everywhere.

Because the moment you start seeing it,

is the moment you start changing it.”

Subscribe now

Other Links From the Talk

Watch on Youtube

Over the past few years, I’ve been building and refining a set of templates to help product teams run meaningful, structured discovery work - from problem framing to delivery.

I’m excited to share that these resources are now live in Miro’s Miroverse, all in one place.

Whether you’re:

• Kicking off a new feature area

• Exploring a complex problem space

• Or iterating on an existing product line

this board is designed to support outcome-driven discovery in a practical, visual way.

What’s Included

Most templates come with workshop instructions and timing guides, so you can run them confidently - even if it’s your first time facilitating.

Here’s what you’ll find:

• Customer journey diagrams

• Problem space definition

• Outcomes and North Star alignment

• Opportunity Solution Trees

• Event storming templates

• Epic breakdown boards

• Pre-mortem planning

• Retrospective templates

• Data Flow Diagrams

• Links to my own working docs, blogs, and product discovery guides

These are the same templates I use in my day-to-day work - designed to help you and your team explore the right problems and ship solutions that deliver real impact.

Got Any Nice Boards You Think I’d Like?

If you try out the board, I’d love to hear how it works for you - or how you’ve adapted it for your team.

Also, if you have discovery templates or workshops of your own that you think would be a good addition, please share! I’m always on the lookout for new and novel ways of working.

🔗 Explore the Continuous Discovery Template in Miroverse

Subscribe now

This one is genuinely easy - and can have such a huge impact.

AI has come a long way in the past couple of years. You don’t need to be an expert in prompt engineering anymore to get a great prompt. You just need to know what you want the prompt to do, and then simply ask AI for the prompt itself.

That’s the idea behind creating your own Personal AI Mentor.

What Is It?

This "Personal AI Mentor" prompt guides you to input your role, career context, and development goals, such as:

• “I want to improve in product strategy.”

• “I’d like to learn more about UX.”

• “I’m trying to get better at focusing on impact.”

It then generates a customised set of AI instructions you can drop into any tool that you can create bots in - like ChatGPT’s Custom GPTs/Projects or a Google Gemini Gem.

My recommendation?

Use Gemini 2.5 Pro - out of the above examples, it gives the most structured and thoughtful output.

Instructions (to get instructions?)

Simply follow the below steps and drop it as instructions in a new ChatGPT Project/GPT or Gemini Gem

1. Replace <bold placeholders below> with your own and send to Gemini advanced (use 2.5 Pro)

I am a <role and title> in <Company name & industry (if name isn’t well known)> and I want to use AI to help me on my day-to-day tasks, better understand complex topics, achieve my long-term career goals and maybe work better with the product team on the products that I support.

I feel like I don't have enough experience in <XYZ>, I want to learn a bit more about <ABC> and I want to explore <CDE> so that I can grow into that area over time.

Can you create a set of custom instructions in markdown format that I can use in Gemini’s Custom Instructions or a ChatGPT GPT?

My Example (Real Output)

I am a senior PM in Toast and I want to use AI to help me on my day-to-day tasks, better understand complex topics, achieve my long-term career goals and maybe work better with the product team on the products that I support.

I feel like I don't have enough experience in strategy, I want to learn a bit more about how to focus on impact and I want to explore UX so that I can grow into that area over time.

Can you create a set of custom instructions in markdown format that I can use in Gemini’s Custom Instructions or a ChatGPT GPT?

My Output

**1. What would you like Gemini to know about you to provide better responses?**

* **My Role & Context:** I am a Senior Product Manager at Toast. Toast provides a comprehensive platform of SaaS products and financial technology solutions for the restaurant industry (e.g., POS, online ordering, kitchen display systems, payroll, capital). My work involves understanding the needs of restaurant owners, operators, staff, and guests.

* **My Responsibilities:** I define product vision, strategy, and roadmaps for my product areas. I write requirements (PRDs, user stories), prioritise backlogs, and work closely with engineering, design (UX/UI), marketing, sales, customer success, and support teams.

* **My Goals & Development Areas:**

* **Strategy:** I want to strengthen my product strategy skills. I'm looking to improve my ability to develop long-term vision, competitive analysis, market positioning, and strategic frameworks. I sometimes feel I lack deep experience here.

* **Impact Focus:** I aim to become better at defining, measuring, and prioritising work based on tangible business and customer impact (outcomes over outputs). Help me focus on the 'why' and the measurable results.

* **UX Interest:** I have a strong interest in User Experience (UX). I want to deepen my understanding of UX principles, research methods (user interviews, usability testing), interaction design, information architecture, and accessibility. My long-term goal might involve moving towards a more UX-focused role or integrating UX expertise more deeply into my PM practice.

* **How I Use AI:** I plan to use you as a thought partner for brainstorming, researching concepts, drafting documents (emails, PRD sections, presentations), understanding complex topics (technical, market trends, UX theories), getting feedback on ideas, improving team collaboration, and identifying learning resources.

**2. How would you like Gemini to respond?**

* **Tone:** Professional, knowledgeable, collaborative, and slightly mentor-like. Act as an experienced peer who understands the B2B SaaS and restaurant tech space.

* **Focus on My Goals:**

* **Strategy Lens:** When discussing features, roadmaps, or problems, proactively ask about or suggest strategic alignment. Prompt me to think about market differentiation, competitive landscape, and long-term vision. Suggest relevant strategic frameworks (e.g., SWOT, Porter's Five Forces, Ansoff Matrix) when appropriate.

* **Impact-Driven:** Frame suggestions and discussions around potential impact. Ask clarifying questions about success metrics, KPIs, and desired outcomes. Encourage me to articulate the value proposition clearly and how we'll measure success. Challenge me if the focus seems too much on features (outputs) rather than results (outcomes).

* **UX Emphasis:** Weave in UX considerations frequently. When discussing user problems or solutions, highlight potential UX implications, suggest relevant UX research methods, point out usability heuristics or design principles, and encourage user-centered thinking. If I'm describing a workflow, ask about the user journey or potential friction points. Suggest ways to incorporate user feedback early and often.

* **Actionable & Concrete:** Provide specific, actionable advice, examples, and suggestions. Don't just give high-level theory; explain *how* to apply it in a practical PM context at a company like Toast.

* **Learning Support:** Explain concepts clearly, especially around strategy and UX. If relevant, suggest reputable articles, books, experts, or online resources for deeper learning on these topics. Break down complex ideas.

* **Contextual Awareness:** Relate your responses back to the restaurant industry and the challenges/opportunities for Toast and its customers whenever possible.

* **Constructive Feedback:** Feel free to challenge my assumptions constructively and offer alternative perspectives, particularly regarding strategy, impact measurement, and user experience.

* **Formatting:** Use Markdown (lists, bolding, italics) to structure responses clearly and improve readability.

Why This Is Worth Doing

We spend a lot of time waiting for feedback or hoping for mentors to appear. But with tools like this, you can generate structured guidance whenever you need it.

You’re creating a self-directed, always-available coach - one that grows with you.

Simply send it the content you are struggling with, topics you want to skill up on, or screenshots of threads or conversations you are replying to - along with your messages - to see if there is anything you haven't thought of that might relate to one of your areas of growth.

If you do create one, tag me or reply in the comments - I’d love to see what your personal AI mentor looks like.

Subscribe now

Want to just snip → paste into ChatGPT, Gemini, Slack, Confluence, Jira, or Miro?

Here’s a faster way:

Update your Mac’s screenshot hotkey:

1. Go to System Settings → Keyboard → Keyboard Shortcuts… → Screenshots

   

2. Look for “Copy picture of selected area to the clipboard”

   

3. Change the shortcut to something else (e.g., Cmd + Shift + C)

4. Hit Done

Now anytime you hit your shortcut:

1. Select the part of the screen you want

2. Just Cmd + V to paste it anywhere instantly

No files, no clutter, simple and fast.

Update: Bonus Tip

1. After using the keyboard shortcut and the crosshair is visible, tap the spacebar

2. The cursor changes from crosshair to a camera

3. As you hover the mouse over any window, it will become highlighted

   

4. Once the window you want to screenshot is highlighted, click the mouse button to capture that window

5. This avoids the need to actually create a selection rectangle

Subscribe now

Earlier this year, I gave a talk at a DesignBrew Meetup on the topic of design-driven collaboration. I’ve re-recorded that talk and posted it, and you can watch it here.

Of all the concepts I shared, one slide stood out: the Personal User Manual. After the talk, multiple attendees mentioned it was the most thought-provoking and useful idea they took away.

It’s simple in concept, but powerful in practice.

A Personal User Manual is a document where you outline how you like to work; your preferences, communication style, feedback approach, and more.

It’s a tool that helps others understand you better and collaborate with you more effectively. And in today’s cross-functional, fast-paced environments, that kind of clarity can really help the culture in teams and in your company.

So Why Create a Personal User Manual?

If you’re someone who:

• Works across multiple projects

• Collaborates with different PMs/leaders or stakeholders regularly

• Is part of a shared resource pool or enabling team

… then a Personal User Manual can remove a huge amount of the guesswork in how people work with you. It opens the door to clearer expectations, smoother collaboration, and fewer misunderstandings.

For example:

If a PM knows you’re happy to receive feedback via Slack threads, they’ll feel more confident giving it there, rather than waiting for a formal meeting.

If praise in public Slack channels makes you uncomfortable, you can say that upfront and avoid that awkward moment entirely.

The result?

• Less friction

• Faster decision-making

• A more cohesive team environment

Try it yourself and fill out your Personal User Manual

Below is the full set of questions that you should answer yourself along with examples of what kind of answers you can have. Take 15 - 20 minutes to reflect and fill it out. Then share it with your team or manager, especially when starting a new project or joining a new team.

You might be surprised by how many assumptions others are making about you (and vice versa). I’ve seen teams catch blind spots and misunderstandings within minutes of sharing their manuals.

The below template is also over on my Miro Template which you can find here. Feel free to copy that board if you see anything that might be useful.

Personal User Manual - Template

My Role and Contributions

• What’s my primary responsibility in the team?

• What are the key areas where I can add value?

My Communication Style

• How do I prefer to communicate (e.g., Slack, email, or in-person)?

• What’s the best way to get a quick response from me?

How I Learn Best

• What’s my preferred way of learning (e.g., visuals, discussions, or documents)?

• How do I stay motivated to absorb new information?

My Approach to Feedback

• What’s my style for giving feedback?

• How do I like to receive feedback (e.g., direct, in writing)?

My Approach to Praise

• How do I like receiving praise? (e.g., public/private slack messages, Recognition tools, Email)

• How do I prefer to give Praise?

How I Collaborate

• What collaboration styles work for me (e.g., brainstorming, structured meetings)?

• How do I involve others in my work?

How to Approach Me

• What’s the best way to raise an urgent issue?

• How can we work through sensitive topics?

My Working Hours

• What hours am I available?

• What boundaries do I have for after-hours work?

What Keeps Me Productive

• What working environment helps me focus?

• What habits or tools help me stay on track?

My Decision-Making Style

• How do I approach decisions (e.g., data-driven, collaborative)?

• What do I need to feel confident about a decision?

What Gets Under My Skin

• What behaviours throw me off balance?

• How can we avoid or manage those situations?

Things I’m Great At

• What are my areas of expertise?

• How can I best support my teammates?

Things I Struggle With

• What challenges do I face sometimes?

• When might I need extra support?

The Personal User Manual is one of those tools that seems almost too simple to be useful - until you try it.

It’s not just about making things easier for yourself. It’s about creating psychological safety for yourself and your co-workers, building stronger team dynamics, and helping others do their best work with you.

If you’re onboarding into a new role or kicking off a new collaboration, give this a try. Share it with your team. You’ll be amazed how much it improves clarity, trust, and alignment from day one.

Already using something like this with your team? I’d love to hear how it’s working for you - drop me a message or comment below.

Subscribe now

I answered a question recently about UX, design and the future of UX leadership roles, and I felt it deserved its own post here.

"How do we lead with vision and empathy in a rapidly changing design landscape, ensuring progress doesn’t come at the cost of sustainability and inclusivity?"

Before the leadership bit - I’d still argue that UX is more important than ever - but now it's just changing in how we define it.

Correct, UX for interfaces isn’t the behemoth it used to be, but in my opinion it's actually just shifting away from interfaces and towards operational UX instead - the experience of internal users navigating complex, broken workflows inside companies.

AI is exposing something about a practice that is widespread across most companies: the massive operational tech debt they’ve ignored for years.

Teams are still handling an incredible amount of manual work that was never properly systematised, especially in companies that scaled quickly.

The old solution was to just throw more headcount at the problem.

This doesn’t work anymore.

The tech debt is becoming too unwieldy, making it hard for big companies to scale quickly and change their features on demand - just like all these new AI companies are doing.

I do think we’re a bit away yet from AI automating all these workflows however, unless they’re first brought into the company’s core systems in a structured way.

So that brings me to your question - what should UX and design leaders focus on?

Well, in my eyes, they should be identifying all the manual processes within a company in order to understand which are the most painful, have the highest friction, and cause the most frustration.

They should also aim to determine which of these processes are easiest to transform into automated flows or be removed entirely. Much of this tech debt is completely redundant and can be eliminated fairly painlessly, considering the amount of grief it causes.

Researching where manual work is driving employee churn is important too, because it’s often these tasks that create the most stress and risk when errors happen.

The challenge is that these inefficiencies aren’t new.

Operational teams have been flagging them for years. It's just that people didn’t listen, or they did, but they didn’t have the capacity to fix them.

That’s where leadership and empathy needs to come in.

UX leaders will have to approach these conversations with stakeholders using empathy, trust-building, and a lot of strategic thinking. In many cases, the work they’re trying to automate could threaten someone’s entire job.

But there’s a better way to do it.

Instead of just removing the highest-risk tasks for the company, you need to focus on the bottom of the barrel.

Start by reducing the most repetitive, low-value work first - this way, you don’t destabilise the ops teams, and you free them up to help you with the discovery on higher-impact, higher-value tasks.

They are the best people to help you design new flows, and the best people to help maintain them.

This is how you need to frame what you are doing: building relationships, doing deep customer discovery and removing the worst pain points for your customers.

True UX.

Subscribe now

UPDATED - Feb 1st 2026 with more details and usage examples

Struggling to make your CV stand out?

Applying for a new role or switching careers?

Need mock interview practice tailored to your experience?

I’ve spent a lot of time over the past year explaining to people how to tell their career story - from how they present themselves on a CV to how they communicate impact in interviews.

After writing about storytelling in CVs (#70) and using AI for mock interviews (#79) - two of my most popular posts - I finally managed to merge both ideas into something actionable.

Presenting to you, The Career Storytelling Expert.

→🔗Link to the GPT in the GPT Store 🔗 ←

Big thanks to James Conway, who sent me a version of custom instructions he created inspired by my storytelling blog. That sparked the idea of turning this into a structured GPT, guiding people step by step through refining their CVs and preparing for interviews - with storytelling at the core.

What Does It Do?

The Career Storytelling Expert has two core functions:

1. CV Refinement:

• Helps you craft a narrative-driven CV that tells your career story

• Asks guided questions about role transitions, impact, and career growth

• Can tailor your experience to specific job descriptions

• Focuses on the “why” behind your career moves, not just the “what”

2. Mock Interview Practice:

• Acts as a hiring manager and runs realistic mock interviews

• Tailors questions to your CV and target role

• Gives constructive feedback after every answer

• Suggests refined versions of your responses

• Adapts follow-up questions based on what you actually said

The Key to Effective Practice: Use Voice-to-Text

Since launching this GPT, I’ve had some really good feedback from people using it for interview prep. But the one thing that makes the biggest difference is this:

Use voice-to-text to answer the questions.

When you practice interview answers by typing them out, you’re rehearsing a version of yourself that won’t show up on the day. You restructure, polish, and trim the rambling without even realising it. But in a real interview, that filter isn’t there. What comes out is the raw, verbal version - and that’s what the interviewer is actually evaluating.

Not the live voice mode - the microphone button (circled above) to dictate your answers. This way, the GPT gets your real verbal response - the same version the interviewer is going to hear. And it coaches you on that, not on some polished answer you’d never actually say out loud.

How to Get the Most Out of It

Two critical tips for realistic interview practice:

1. Use voice-to-text to answer questions (not typing)

   • Captures your actual verbal delivery

   • Reveals patterns, filler words, and structure issues

   • Matches what the interviewer will actually hear

2. Upload your CV before starting

   • In a real interview, the hiring manager has it in front of them

   • Giving the GPT this same context = more realistic, tailored questions

   • Questions will be specific to your experience and target role

Real(ish) Example: Support Engineer → Product Manager

To demonstrate how it works, I ran a mock interview as a Support Engineer looking to move into Product Management. I didn’t have AI when I made the transition to product (more on that here - How to Become a Product Manager (#94)) but this is how I would use the GPT if I was making that move today.

The GPT picked up on strengths in my answer, coached me on tone, and when I pushed back on its feedback, it offered three different ways to reframe my response. This kind of adaptive, nuanced coaching is what makes it valuable for interview prep.

Who Is This For?

Whether you’re:

• Navigating redundancy (I went through it myself almost exactly 2 years ago at time of update - it’s rough, I know)

• Making a career switch (like the Support Engineer → PM example above)

• Just want to sharpen how you tell your story in interviews

This tool is built for that.

Try It Out

Give it a try and let me know what you think!

I would love to hear feedback from anyone using it for job applications, career changes, or interview prep, and hear of any tweaks you’d like to see.

→🔗Access The Career Storytelling Expert GPT 🔗 ←

Related Posts

I focus on how designers can take the lead in collaborating with product managers, ensuring that design remains central to decision-making. While originally intended for a design audience, the content is relevant to anyone in the tech industry.

You’ll find actionable strategies for structuring communication, improving alignment, and using automation to make collaboration more efficient. Whether you’re working across multiple teams or embedded in one, these insights will help you drive better outcomes in your work.

Key Takeaways & Topics Covered:

✔ Owning the Designer-PM Relationship – Why designers should proactively shape collaboration instead of waiting for PMs to define it.

✔ Effective Communication Strategies – Why threading, structured messaging, and well-timed updates make a difference.

✔ Establishing Clear Ways of Working – How to create and document team norms to prevent confusion and inefficiencies.

✔ The Role of Personal User Manuals – A simple yet powerful tool for aligning expectations and avoiding misunderstandings.

✔ The Power of Organization & Automation – How templates, structured communication, and Slack automation can save time and improve collaboration.

✔ Dealing with Difficult PMs – How to protect yourself from political or credit-taking PMs while maintaining strong collaboration.

See Slides Here

Resources & Links

Call To Action

Enjoyed this episode? Subscribe to the podcast, leave a review, and share it with your team! If you’re ready to improve your collaboration with PMs, start by implementing a personal user manual or refining your ways of working - and let me know how it goes!

Subscribe now

If you follow my blogs it should come as no secret that I am a big fan of AI for productivity. One tool that I have found surprisingly useful in this area is Zoom AI.

If you do have it enabled for use in your company, follow the below instructions to maximise the benefit you can get from enabling the Zoom settings in a certain way.

The settings the way I have them below work best when set by the person who is organising and running the regular scheduled meetings on your team, so after trying these out yourself, feel free to share this blog with them to let them try it out themselves.

Accessing Key Settings

To configure Zoom AI for optimal productivity, follow the guide below and adjust the following settings via your browser.

You will need to replace the [companykey] in the links below with whatever the web version of your Zoom instance is.

Configuring the AI Companion

AI Companion Settings Link

Turn on all AI Companion options to enable features like meeting summaries, highlights, and searchable transcripts.

I encourage this top checkbox here, but some people may not be comfortable with the companion being on from the beginning on each meeting. You won’t be automatically sharing these on any meetings apart from ones where you want to, so this can be a discussion between yourself and the people on the call.

I think once people see the benefit, they’ll quickly be won over.

NOTE: Summaries and transcripts should only be sent to hosts and co-hosts to avoid accidental sharing of sensitive information. This prevents situations where unintended recipients, such as customers, might receive internal discussions.

Smart Recording Setup

Recording Settings Link

Now, there is a lot going on here, and some of these settings may be deactivated by your Zoom admin. Having everything like I have below just makes it take a bit longer to download. Some things you may not need to enable, below are the settings you might want to consider.

All of the settings that start with “Record” allow you to capture separate files for screen sharing, active speaker views, and audio.

These options are particularly useful for creating polished training content, editing audio tracks separately or sharing materials without including the video or individual voice tracks of participants.

Note: some of these settings are only necessary for people who are actively editing media content and using it for marketing for example. However, I suspect at some point in the near future, we will be able to upload audio files to be assessed by AI, and it may prove useful then to avoid adding customer recordings to AI for example.

Turn off the option to “Record to computer files” seen here. This prevents you from accidentally hitting the wrong button when starting the recording of a meeting, and not getting any of the AI summaries or abilities.

Meeting Settings

Meeting Settings Link

Settings that you should have in this area

Disable the waiting room feature to allow participants to join in your absence. This ensures meetings proceed without delays and transcripts are captured from the beginning. This is also very useful if you can’t make a meeting and still want the summary after, or if you are on leave and want a list of all the summaries on your return

Enable the “Allow Zoom Rooms to become the host if they join before meeting host and other participants” as this allows other people to kickstart the recording or transcript in your absence, if you don’t have it set to start automatically.

Enable the “Allow participants to join before the host” option to further streamline meetings, especially for recurring stand-ups or sessions where the host might not always be present. I believe if you only enable this one and not the previous one, the meetings will still continue, but the atendees won’t be able to start a recording or transcript in your absence

This one isn’t AI, but it is probably one of my biggest pet hates when people join a meeting unmuted. Enable this regardless of everything else. Nobody needs to hear someone breathing down the line on a call with 30 people.

Benefits of AI Summaries

AI summaries are actually pretty good! They are concise and cover essential meeting points, making them a fairly reliable alternative to full transcripts.

They are particularly helpful for:

• Stand-ups where action items and key updates are summarised efficiently.

• Catching up on missed meetings quickly after time off or busy days.

• Forwarding to people who may have joined meetings for a workshop and have action items assigned to them

Using Summaries Strategically

Configure the AI Companion as mentioned in the first step to automatically send summaries to co-hosts. This reduces manual effort in forwarding transcripts or summaries after meetings.

Summaries provide a quick recap of who said what during meetings. They can replace manual note-taking for most sessions, making your workflow more efficient.

Organising Co-Hosts and Summaries

This section paired with the the one above where you send summaries to co-hosts is really useful, as then everyone gets the summary who is a co-host, removing the need for you to take down follow on tasks.

Adding Co-Hosts to Meetings

Go to the Zoom meeting settings for recurring or one-off meetings.

Note: this is easiest done in the Zoom desktop app, by hitting the edit button on the meeting in question. For recurring meetings, ensure you identify the correct series in Zoom, and make sure to pick all meetings in the series if you want to do it for them all.

Using the Zoom app like below avoids the issue where you see recurring meetings persisting in the Zoom web app even after being deleted from your calendar

Click on Meeting settings

Scroll to the “Alternative Hosts” section and add team members who frequently join these meetings and should get the transcript.

This ensures they receive transcripts and summaries automatically, even when you’re not present.

By assigning alternative hosts, summaries and transcripts are automatically emailed to them, streamlining follow-ups and reducing administrative tasks.

NOTE: You need to recreate the Zoom links in all of your existing meetings when you change settings, or else old settings will persist.

ADDITIONAL NOTE: If you have two ways of creating Zoom meetings on your calender invites, please also use this above method for creating Zoom meetings. For some reason, the “Make it a Zoom Meeting” button has issues retaining selection of some of the settings.

Adding a Gmail Filter for Summaries

I would encourage setting up a gmail/outlook filter for the summaries, so you can quickly find them when you need to.

Here’s how you can set that up in gmail.

Summarising Summaries in Gemini

(bit of a mouthful that title)

I suspect this piece will become a blog of its own as I have only had access to Gemini for a few days.

With Gemini, you can connect to your gmail in the extensions tab, and then query Gemini to summarise all the different summaries and sort them by person.

This script works OK, but It doesn’t seem to find all emails. I need to play around with it a bit more - but if you use it, tweak it and get it to work - please let me know!

Please analyze all emails with the 'Zoom/Meeting Summaries' label in my mailbox. For any email that was delivered in this calendar month (January 2025) Provide the following:

1. A numbered list of summaries with 1/2 sentence summary of the Quick Recap in the email, including the date.

2. A consolidated list of all to-do items, grouped by assigned person (if names are available). For each to-do item, include a citation referencing the number of the summary it came from.

Example format:

Summaries:

[Date] - [Brief summary of quick recap]

[Date] - [Brief summary of quick recap]

...

To-Do Items:

[Person's Name]:[To-do item] (Summary #)

[To-do item] (Summary #)

[Another Person's Name]:[To-do item] (Summary #)

...

Unassigned:[To-do item] (Summary #)

[To-do item] (Summary #)

...

I have some other AI content here if you found this useful.

For my past blogs check out my most popular posts here or check out the hashtag #JohnsTipOfTheWeek on LinkedIn.

I’d love if you subscribed! I’m trying to build a bit of a following to try and help folks in the industry and make their jobs a little bit easier.