The database migration that needed a DBA who was on leave. The client contact who stopped replying for three weeks. The staging environment nobody owned. None of these were tickets. All of them cost us more than any bug we shipped.

I only got a clean vocabulary for this when I started studying project management properly. The distinction turns out to be small, old, and genuinely useful — so I want to hand it over without the certification padding.

The distinction: an issue is not a risk

Here is the whole thing:

• A risk is a problem that might happen. Future, probabilistic.

• An issue is a problem that is happening. Present, certain.

• When a risk materialises, it stops being a risk and becomes an issue.

That last line is the useful part. Risks are not a list you write once at kickoff and never revisit — they are supposed to graduate. "The lift supplier might get held up at customs" is a risk. The morning the lifts are actually sitting in a customs warehouse, it is an issue, and it needs a different response: not monitoring, but an owner and an action today.

Most teams I have seen have no mechanism for that transition. The risk list lives in a document from month one. The issue nobody saw coming lands in standup as a surprise. It was not a surprise — it was on page two.

Why your tracker can't hold this

Nothing stops you putting "lifts stuck at customs" in Jira. People do. It is just that the tracker is already doing a different job, and the two jobs fight.

Your tracker holds work you intend to do. Issues are problems blocking work you already planned. Mixed into one backlog:

• The blocker gets a priority label and sits in a column with forty other things.

• It has an assignee — but the assignee is usually whoever will do the work after the blocker clears, not the person who can clear it. Those are frequently different people, and often the blocker-clearer is not an engineer at all.

• It has no escalation path. A ticket's escalation is "move it up the backlog". A real blocker's escalation is "this needs the sponsor to make a call by Thursday".

• It closes when the code merges. But most impediments are cleared by a conversation, a decision, or a payment — nothing merges, so nothing closes.

The mismatch is not about tooling. It is that one of these is a work queue and the other is a blocker list, and a blocker list is read by different people, at a different cadence, with different authority to act.

RAID, in ninety seconds

The frame this comes from is RAID — four registers, kept separately because they get different treatment:

It looks like bureaucracy. In practice, for a team of any size, it is four lists and a weekly ten minutes. The value is almost entirely in the separation — assumptions in particular, because an unexamined assumption is the single most common way a plan quietly becomes wrong.

What actually changes in practice

Four things, and they are cheap:

One named owner per issue — a person, not a team. "Platform team" owns nothing. Unowned issues drift, and drift is the default state of a blocker that is inconvenient for everyone.

A date, not a priority. Priorities inflate until everything is P1. A date is falsifiable: Thursday arrives and either it moved or it did not.

An explicit escalation path. Before you need it. "If this is not cleared by Thursday, it goes to X." Most blockers persist not because they are hard but because nobody knew who was allowed to decide.

Review and close, in a fixed cadence. The failure mode of every issue log is becoming a graveyard — forty open entries, half resolved months ago, nobody trusting it enough to read it. A log nobody trusts is worse than no log, because it creates the feeling of control without any.

The part that reframed the job for me

In the PM literature this task is not called "track issues". It is called remove impediments — and the framing is deliberate. Tracking is bookkeeping. The job is clearing the path in front of your team.

That reads as soft-skills fluff until you notice it changes what you do on a Tuesday. Logging "waiting on legal review" is bookkeeping. Walking to legal, finding out the review is stuck on a question nobody asked them, and answering it — that is the job. The log exists to make sure you know which path to clear, not to be the work itself.

For anyone moving from senior dev toward lead or EM: this is a large part of what the role actually is, and it is nearly invisible from the IC seat. It looks like someone going to a lot of meetings. Sometimes it is. Sometimes it is the only reason your sprint finished.

If you want the longer version

I have been writing up the PMP exam content as practical lessons while studying it, with worked examples — the one on issue logs and removing impediments is here. It covers the risk→issue escalation path in more detail, and what the exam expects you to do when a blocker appears (short version: act to clear it, don't just log it).

Full disclosure: I build VanillaPM, an open project management tool, and the lessons are part of it. They are free and ungated — I wrote them to learn the material myself, and publishing them seemed better than letting the notes rot in a folder.

The one thing worth stealing from this post, if you take nothing else: separate the problems that are happening from the work you intend to do. They need different owners, different cadences, and different people reading them. One backlog cannot do both jobs, and the one it quietly stops doing is the one that sinks projects.

I wanted the generate button anyway, because there's a real version of it. Here's how I built a charter generator that drafts genuinely useful prose from the user's actual data, and refuses to make things up — in Django, bring-your-own-key, no framework magic.

Two things this is not

Not autopopulate. I already had a deterministic autopopulate: copy the sponsor from the project record, the dates from the schedule, and so on. That's great for fields, but a charter is mostly prose — a scope statement, an objectives section, a rationale — synthesised from the pre-project inputs (the business case, the benefits plan, the agreements). You can't str() your way to a scope statement. Autopopulate structurally can't do it.

Not a free-form LLM. The other extreme — "here's the project name, write me a charter" — is exactly the hallucination machine. The model has no idea what your business case says, so it invents a plausible one.

The useful thing lives in between: grounded synthesis. Read the real input documents, and ask the model to compose — using only what's actually there.

Step 1: ground in the real inputs, not the model's imagination

The whole trick is that the model's only source of truth is text you supply from the user's own documents — never its training data.

In VanillaPM every document type declares its input documents (its ITTO prerequisites — the things that must exist before it). A charter's inputs are the business case, the benefits management plan, the agreements. So "grounding" is concrete: go read those documents.

DOC_CHAR_CAP     = 8_000    # per input document
TOTAL_CONTEXT_CAP = 40_000  # the whole grounding context

def input_documents(project, doc_type):
    """(type, title, text) for each declared prerequisite that exists and has
    readable text — each capped so one long doc can't dominate the context."""
    out = []
    for prereq in prerequisite_types(project, doc_type):   # from the dependency graph
        doc = latest_of_type(project, prereq)
        text = document_text(doc)          # walk the stored rich-text → plain text
        if text:
            out.append((prereq, doc.title, text[:DOC_CHAR_CAP]))
    return out

Two boring-but-important details:

• Cap per document and in total. One 200-page attachment shouldn't crowd out the other inputs (or blow your context window / bill). A per-doc cap plus a total cap keeps the grounding balanced and bounded.

• Ground in authored text, not the whole DB. document_text() walks the document's stored rich-text tree and pulls the prose the human actually wrote — not a JSON dump of every model.

The grounding context is then just: the deterministic structured facts (reused from autopopulate) + these input-document excerpts, under a big honest header.

Step 2: the system prompt does the anti-hallucination work

This is the part people skip. The model will fabricate unless you make refusing the easier path. Three rules, and the second one is the whole ballgame:

SYSTEM_PROMPT = (
    "You draft sections of a PMBOK-aligned project document.\n"
    "1. Ground every section ONLY in the provided project data and input "
    "   documents below. They are your only source of truth.\n"
    "2. If the data a section needs is missing, write ONE short professional "
    "   sentence stating what input is still needed — do NOT fabricate.\n"
    "3. Return JSON only: "
    '{"sections":[{"key":"<section_key>","body":"<prose>"}]}. '
    "Use only the section keys given. No markdown headings, no preamble."
)

Rule 2 is the difference between a demo and a tool. Giving the model an acceptable way to say "I don't have this" — a short "needs input: the benefits plan doesn't state a target ROI" placeholder — means it takes that exit instead of inventing a number. You're not just asking it not to hallucinate; you're handing it a better move than hallucinating.

The user turn wires the sections to draft onto the grounding context:

USER_PROMPT = (
    "Draft these sections of the project's {doc_label}. Use each key exactly:\n\n"
    "{targets}\n\n"
    "=== PROJECT DATA AND INPUT DOCUMENTS (your only source of truth) ===\n"
    "{context}"
)

Structured JSON out, fixed keys in. The model returns {"sections":[{"key", "body"}]} and may only use keys I gave it. That does two jobs: parsing is trivial and deterministic, and the model can't wander off and invent a "Section 12: Executive Bonus Plan." It fills the blanks I asked for, or it says it can't.

Step 3: only touch the blanks, never the real data

A charter is a mix of authored prose sections and live-data sections (a stakeholder table, a risk snapshot) that are generated from real records. The AI must never touch the latter — those aren't opinions to draft, they're facts to render.

def target_sections(content_json, overwrite=False):
    for node in content_json.get("content", []):
        if section_has_datablock(node):        # a live register/table snapshot
            continue                           # generated from real data — hands off
        if section_has_text(node) and not overwrite:
            continue                           # non-destructive: only fill empty sections
        yield node["attrs"]["key"], node["attrs"]["title"]

So the fill is non-destructive (it never overwrites what a human wrote unless they ask) and it skips live-data sections entirely. The model works on empty prose sections and nothing else. Bonus: because the section keys/titles come from the document itself, the exact same code drafts a communications plan or a risk-management plan — it generalised for free.

And the output lands in draft, for a human to review and approve. The AI proposes; the PM decides. It's never a fact until a person signs off.

Step 4: bring-your-own-key, and fail safe

No forced AI markup, and no crash when AI isn't configured. The path resolves BYOK-first:

def resolve_ai_path(user, org):
    if byok_available(user, org):                     # user's own key
        return "byok", user_key(user), MODEL_BYOK     #   → free through us
    if managed_available(user, org):                  # metered credits
        return "managed", server_key(), MODEL_MANAGED
    return None, None, None                           # feature cleanly disabled

And the SDK import is guarded — a server without the anthropic package (or a user without a key) degrades to a disabled button, never an exception:

try:
    import anthropic
    _AVAILABLE = True
except ImportError:
    anthropic, _AVAILABLE = None, False

Nothing in the module holds a key; the caller passes the user's decrypted key in per request. (Load tests swap in an offline stub so they never hit the real API — cost and rate limits stay off the test path.)

What grounding buys you — and what it doesn't

Grounding isn't a hallucination cure; it's a hallucination budget. What it reliably buys:

• The model composes from your business case, so the objectives are your objectives.

• Missing inputs surface as honest "needs input" notes — which doubles as a checklist of what to go write.

• Structured, key-scoped output means no invented sections and trivial parsing.

• Non-destructive, draft-only, human-approved: the AI can't silently rewrite a governed document.

What it doesn't do: it won't fix a vague business case (garbage in, grounded-garbage out), and a determined model can still mis-synthesise. So it's a draft generator with a human gate, not an autopilot — which is exactly what a governed document deserves.

The pattern generalises well beyond charters: read the real inputs, cap and label them as the only source of truth, give the model an honest "I don't know," constrain the output shape, and never let it touch data it should only render. That's most of the distance between "we added AI" and AI you can actually put near real work.

I'm building a free, full-lifecycle PM platform in the open — this generator ships in it (BYOK). If the build-in-public engineering is your thing, the rest of the series is here.

Here are the patterns that kept it maintainable, and the gotchas that cost me real hours. All of it is stuff I wish someone had told me at line 1.

The mental model: islands, not an app

The trap with Alpine in a big project is treating it like a mini-SPA — global stores everywhere, components reaching into each other. Don't. Treat each interactive region as an island: a self-contained Alpine component hydrating one chunk of server-rendered HTML. The server owns the data and the page; Alpine owns this widget's behaviour.

Two rules fall out of that, and they're the difference between "fine at 10 screens" and "fine at 200."

Rule 1: register components — stop writing logic inline

Inline x-data="{ ... }" is lovely for a toggle. For anything real, it's a liability — and it has a nasty failure mode.

Put a literal double-quote inside an inline expression and you silently close the HTML attribute early:

<!-- ❌ Alpine sees x-data="{ label: "  — the rest becomes broken markup -->
<div x-data="{ label: "Save", open: false }">

The component doesn't throw. It just… doesn't initialize, and depending on where the parser gives up, your expression can dump into the page as visible text. Worse, it often renders fine in your quick manual check but breaks somewhere else — and it's invisible to a lot of smoke tests because it's an HTML-parse issue, not a JS error.

The fix isn't "remember to use single quotes." It's: anything beyond a line or two becomes a registered component.

// static/js/components.js
document.addEventListener('alpine:init', () => {
  Alpine.data('projectBoard', () => ({
    open: false,
    label: 'Save',           // real quotes, real editor, real linting
    toggle() { this.open = !this.open },
  }))
})

<div x-data="projectBoard"> … </div>

Now the logic lives in a .js file your editor and linter understand, the template stays declarative, and the quoting footgun is gone.

Rule 2: never put a "rich" JS instance on reactive state

This one cost me the most time, so I'll be specific. Alpine makes your state reactive by wrapping it in a deep Proxy (via @vue/reactivity). That's great for plain data. It's poison for objects that do their own identity bookkeeping internally — a TipTap/ProseMirror editor, a map instance, a <canvas> controller, a WebSocket.

// ❌ ProseMirror starts throwing "Applying a mismatched transaction"
Alpine.data('editor', () => ({
  editor: null,
  init() { this.editor = new Editor({ element: this.$refs.box }) }, // now a Proxy
}))

The editor stores references to its own nodes/state and compares them by identity. Once Alpine has proxied it, this.editor is not the object the editor thinks it is, and its internal === checks fail in baffling ways.

The fix: keep non-plain instances off reactive state entirely. A closure is cleanest:

// ✅ the editor lives in closure scope — never proxied
Alpine.data('editor', () => {
  let editor
  return {
    init()    { editor = new Editor({ element: this.$refs.box }) },
    bold()    { editor.chain().focus().toggleBold().run() },
    destroy() { editor?.destroy() },
  }
})

If it must live on this, mark it so the reactivity engine skips it (obj.__v_skip = true before assigning, i.e. markRaw). But closure scope is simpler and I reach for it every time. Rule of thumb: only plain, serializable data goes on x-data.

Rule 3: x-data initializers snapshot — use init/x-effect for async

x-data runs once, eagerly, and takes whatever the expression evaluates to right then.

<!-- ❌ `stats` is the Promise fetchStats() returned, not the resolved data -->
<div x-data="{ stats: fetchStats() }">

You'll see [object Promise] or stale/empty state and chase it for an hour. Load then assign:

<div x-data="{ stats: null, async init() { this.stats = await fetchStats() } }">
  <template x-if="stats">…</template>
</div>

Same shape bit me with theme switching: reading a value once at init captures it forever. If something needs to react to a change (a store value, a media query, a fetched result), it belongs in x-effect or an explicit assignment — not in the initializer expression.

Rule 4: pass server data as data, not string interpolation

The tempting thing is to jam Django context straight into an Alpine expression: x-data="{ items: {{ items }} }". It works until a value contains a quote or a newline, and then you're back in Rule 1's parser hell. Use Django's json_script:

{{ items|json_script:"board-data" }}

<div x-data="{ items: JSON.parse(document.getElementById('board-data').textContent) }">

Server renders JSON safely into a <script type="application/json">; Alpine reads it. Clean separation: Django owns the data, the template just carries it, Alpine consumes it.

The small Django-template traps

Two that bit me more than once:

• {# … #} is single-line only. A comment that wraps across lines renders as literal visible text — and if it's sitting next to an Alpine attribute, chaos. Use {% comment %} … {% endcomment %} for anything multi-line.
• Shared islands, single-sourced. The nav bar, the sidebar, the top bar — build each as one island partial you include everywhere, not a per-page fork. The day I stopped copy-pasting the nav component was the day the footer stopped mysteriously drifting between pages.

What "sane" ended up meaning

Nothing exotic — just discipline:

1. Islands, not a SPA. Server owns data + page; Alpine owns a widget.
2. Register non-trivial components in a JS file; inline only for toggles.
3. Plain data only on x-data — rich instances live in closures.
4. Async loads via init/x-effect, never the initializer expression.
5. Server → client via json_script, never string interpolation.
6. A browser smoke run as a release gate, because the worst Alpine bugs are HTML-parse issues that pass unit tests.

Alpine scaled to a genuinely large app for me — but only once I stopped treating it like React-lite and started treating it like sprinkles on server-rendered HTML.

I write these while building a free, full-lifecycle PM platform in the open — if the build-in-public stuff is your thing, the rest of the series is here.

"It's genuinely free? How are you going to survive?"

Fair question. Here's the honest answer — including the part where I admit I don't have it all figured out.

First, what "free" actually means here

Not a free trial. Not free-for-3-users-then-a-wall. The entire core is free — the full PMBOK 8th-edition lifecycle, charter to closeout, WBS, Gantt, Earned Value, risk registers, a knowledge base, sprints. No seat limits. No paywall on the thing itself. New accounts even open a fully-built sample project so you can use everything on real data before you create anything.

I did that on purpose, and it wasn't a growth hack.

Why free — the real reason

The tools that genuinely teach you project management are locked behind enterprise pricing. The ones you can actually afford don't teach you anything — they're glorified to-do lists. So the people who most need to learn how to run a project — a student, a freelancer, a first-time founder, a small NGO running on grants — are the exact people priced out of the tools that would teach them.

I wanted to close that gap. Free removes the friction for precisely the people who need it most. That's the whole point, and a paywall on the core would defeat it.

The bigger bet

Here's the part that reframes the "how will you survive" question: VanillaPM isn't "a free PM tool." It's the first module of a teaching business suite.

Project management is the front door because it's where most people first hit the wall. But finance, HR, payroll and org design are already being built on the same spine — the idea being that a small org could eventually run its whole operation, and learn how to, in one place. Free PM is distribution and trust. The moat is the teaching and the breadth that follows.

So… how do I plan to survive?

Honestly? I have directions, not a locked plan — and I'd rather tell you that than pretend I have a tidy spreadsheet.

What I'm considering (none decided):

• Managed AI, not manual AI. Bring-your-own-key AI is free. But hosting the AI — no key, no setup, it just works — is a real cost I could reasonably charge for. Convenience, not capability.

• Depth for organisations. The ERM finance-to-payroll suite, org-scoped access control at scale, multi-entity separation — the stuff a company needs, not a student. That's where willingness-to-pay actually lives.

• Hosted / support / SLA tiers for teams who want someone on the hook.

• The teaching layer — deeper courses, certifications-prep, guided tracks.

What I will never do:

• Paywall the core PM lifecycle. It stays free.

• Seat-limit the free tier into uselessness.

• Sell your data. Ever.

The principle I keep coming back to: money should come from depth and convenience, not from holding your project hostage. The free core is a promise, not a funnel with a trapdoor.

The honest risk

This might not work. "Free core, charge for depth" is a real model (it's how a lot of good software gets distributed), but plenty of founders have gone broke being generous. I know that.

I'm building in public partly because I don't have it fully solved — the feedback is the point. Free-first is a deliberate bet: distribution and trust now, revenue later, from the people and orgs who get enough value that paying feels obvious rather than extracted.

Ask me again in a year and I'll show you the numbers — the good and the bad. I've been sharing the flops too (my first ad: $3, some clicks, zero signups), and I'm not going to stop.

Your turn

If you've built or used a free-core product: how would you monetise this without betraying the "free" promise? Genuinely asking — the comments on posts like this have already changed my thinking more than any strategy deck.

And if you just want to poke at a free, full-lifecycle PM platform (no signup wall — there's a sample project waiting): it's at vanillapm.com.

I'm a developer of ~13 years who spent the last few leading delivery, and I wanted to genuinely learn formal project management — not from slides, but by building the tool I wished existed. This is the honest breakdown: what it cost in money, where the real leverage came from, and a few lessons that surprised me.

What it actually cost

Total to a shipped, tested, deployed 1.0: under $700. No team, no seed round, no office — a $17/month VPS, a mailbox, and some AI credits.

The line item that matters most is the smallest: that $150 of AI credits is the one that changed what "solo" even means.

The real lever: AI as a force multiplier, not an autocomplete

The interesting part isn't that AI wrote code. It's that it let one person hold the whole system in their head at team throughput. Scaffolding a new Django app, writing the tests alongside the feature, doing the third tedious refactor of the day, rubber-ducking an architecture decision, and — genuinely — teaching me the PMBOK concepts while I built the features that implement them.

It is not magic, and it doesn't replace judgment. You still architect. You still decide. You still verify everything, because the model is confidently wrong often enough that trusting it blindly would sink you. But the throughput multiplier is real, and the shape of "what a solo developer can ship" has changed.

Some concrete numbers from the three months:

• 58 Django apps
• ~84,000 lines of Python (excluding migrations)
• 320 migrations of schema evolution
• 2,000+ tests, behind a CI gate that blocks any merge on a failing test or a coverage drop

Every task got its own branch, ran tests + lint + a makemigrations --check on every change, and merged with --no-ff. That discipline is the thing AI didn't replace — it amplified it.

Four lessons that surprised me

1. Tests are what make solo + AI safe. Those 2,000 tests aren't a vanity metric — they're the safety net that lets you refactor fearlessly and trust an AI-assisted change you didn't hand-write line by line. Without them, the speed becomes a liability. With them, it compounds.

2. Building the PM tool taught me PM better than any course. I ran the build of VanillaPM as a VanillaPM project — a real charter, a WBS, sprints, formal change control on my own scope. Dogfooding turned abstract PMBOK concepts into muscle memory.

3. The boring infrastructure decisions compound. Postgres end-to-end, object storage for files, a fail-closed search-indexing gate, automated backups, a health-checked deploy. None of it is exciting. All of it is why the thing stays up.

4. Scope is the enemy, and formal change control on your own project keeps you honest. The number of "small" features I talked myself out of via my own change process is the reason 1.0 shipped at all.

Why it's free

The tools that actually teach you project management are locked behind enterprise pricing; the ones you can afford don't teach you anything. I wanted to close that gap — a place where a student, a freelancer, or a small NGO can run a real project (and learn how) without a paywall. New accounts even drop straight into a fully-built sample project — a 220-room hotel build with a real WBS, schedule, budget and risk register — so you can explore everything on real data before creating anything of your own.

There's also a free Learn PMP course and an ITTO memory game for exam prep, in seven languages.

If you want to look

It's at vanillapm.com — free, no trial, no seat limits. I'm building the rest in public and I'll keep sharing the numbers, including the unflattering ones (my first paid ad: $3, a handful of clicks, zero signups — but that's another post).

If you're a developer curious about the solo-plus-AI workflow, or a PM tired of enterprise pricing, I'd genuinely love your feedback in the comments. What would you have built differently?