Mert

The Imperative of Inclusive Open Source

Open source software is the backbone of modern technology, yet its full potential remains untapped if accessibility is an afterthought. A recent GitHub Community discussion, initiated by mlama007, brought to light a crucial new resource: an Accessibility Best Practices Guide for Open Source Projects. This guide offers maintainers practical, actionable steps to ensure their projects are usable by all, directly impacting overall project quality and aligning with key engineering OKRs focused on user experience, inclusivity, and delivery efficiency.

“Nothing About Us Without Us”: A Core Principle for Engineering Leadership

The guiding philosophy of the new accessibility guide is profound: “Nothing about us without us.” This emphasizes the critical need for engineering teams and product managers to partner with people with disabilities early and often throughout the development lifecycle. As P-r-e-m-i-u-m highlighted in the discussion, treating accessibility as an integral part of the process, rather than an afterthought, is a game-changer for open source projects. It’s not merely a compliance checkbox; it’s a strategic move that enhances product quality, reduces technical debt, and broadens your project’s reach. For technical leaders, this means fostering a culture where inclusive design is a non-negotiable aspect of every feature, influencing everything from initial design sprints to post-release maintenance.

Continuous Integration/Continuous Delivery (CI/CD) pipeline with an integrated accessibility testing step.## Actionable Steps for Accessibility Excellence

The guide breaks down complex accessibility concepts into manageable, impactful steps. Here’s a summary of key takeaways and community-contributed enhancements that can elevate your project’s accessibility posture:

Starting Strong with Documentation and Design

• Accessibility Statement & ACCESSIBILITY.md: The guide provides a template and example for creating an ACCESSIBILITY.md file. This document serves as a public commitment to accessibility, informs users about the project’s current status, and outlines any known limitations. It’s a foundational step that communicates intent and transparency.
• Accessible Documentation by Default: Simple practices like using proper headings, adding descriptive alt text to images (as suggested for the README), and providing captions for media ensure that project documentation itself is accessible. This sets a standard for all content creators within the project.
• Designing Accessible Interfaces: Core principles include robust keyboard support for all interactive elements, correct semantic HTML, and thoughtful consideration of color contrast. These elements are crucial for users relying on assistive technologies or those with visual impairments.

Integrating Accessibility into Your Development Workflow

True accessibility isn’t built in a vacuum; it’s woven into the fabric of your development process. This is where the guide truly shines, offering practical integrations:

• PR Checklists and Issue Templates: Building accessibility checks directly into your Pull Request (PR) checklists ensures that every code contribution considers inclusive design from the outset. Similarly, dedicated accessibility issue templates, including the suggested “a11y regression” label from Gecko51, streamline reporting and prioritization. This proactive approach helps maintain a high standard of quality and can be a key metric in development performance review examples for teams committed to excellence.
• Continuous Testing with CI/CD: Automated accessibility testing in your Continuous Integration/Continuous Delivery (CI/CD) pipeline is non-negotiable for modern development. Gecko51 specifically recommends tools like axe-core with jest-axe for component-level testing or @axe-core/playwright for end-to-end flows. Pairing this with a Lighthouse accessibility audit step in your GitHub Actions workflow offers comprehensive coverage without slowing down your pipeline. These integrations provide immediate feedback, preventing accessibility issues from reaching production.

Magnifying glass highlighting accessibility details of a UI component: keyboard focus, alt text, and color contrast.### Leveraging Tools and Expertise

• GitHub Copilot for Accessibility Tasks: The guide suggests leveraging AI assistants like GitHub Copilot to help with accessibility tasks, such as generating semantic HTML or suggesting appropriate ARIA attributes. While AI is a powerful aid, human oversight remains critical.
• ARIA Authoring Practices Guide (APG): For complex UI patterns, the ARIA Authoring Practices Guide (APG) at w3.org is an invaluable resource. Linking this directly in your ACCESSIBILITY.md empowers developers with pattern-by-pattern implementations for elements like tabs, modals, and comboboxes, ensuring correct semantics and behavior.
• Partnering with the Disability Community: The core message, “Nothing about us without us,” extends to testing. Platforms like Fable and Access Works, mentioned by Gecko51, connect development teams with disability community members for paid usability testing. This direct feedback is invaluable, offering insights that automated tools simply cannot capture, and ensuring your project truly meets user needs.

Beyond Compliance: Driving Engineering Excellence and Achieving OKRs

Integrating accessibility is more than just meeting compliance standards; it’s a strategic investment in your project’s future. By making your open source project accessible, you:

• Expand Your User Base: You open your project to a wider audience, including millions of users with disabilities, potentially increasing adoption and contributions.
• Improve Overall Code Quality: Adhering to accessibility best practices often leads to cleaner, more semantic code, which is easier to maintain and extend. This reduces technical debt and improves long-term project health.
• Enhance User Experience for Everyone: Many accessibility features benefit all users. Clearer navigation, better contrast, and robust keyboard support make an application more pleasant and efficient for everyone.
• Align with Key Engineering OKRs: Projects that prioritize accessibility often see improvements in metrics related to user satisfaction, bug reduction, and code quality. This directly contributes to achieving engineering OKRs focused on product excellence, user retention, and efficient delivery. While not always directly visible on typical engineering dashboard examples, the impact on user engagement and overall project health is undeniable.

Start Small, Make a Big Impact

You don’t have to do everything at once. The guide encourages starting small. This week, consider one or two of these initial steps:

• Add an ACCESSIBILITY.md file to your project.
• Ensure every interactive element is keyboard reachable.
• Fix missing form labels.
• Add alt text to images in your README.

Every fix opens the door for someone who couldn’t use your project before. That’s a win worth celebrating, and a testament to truly inclusive engineering.

The old PR review system ran Gemini on every submission to the claude-code-plugins repo. It broke every time — quota errors, timeout, malformed JSON, the works. On 2026-05-15 I shipped a replacement and deleted the original on the same day.

The replacement is structured around two contracts. A deterministic classifier scores each submission against 12 rules and emits one of three verdicts. A Groq LLM bolted on top writes a 5-line summary as advisory polish. The deterministic layer is the product. The LLM never blocks.

The first live invocation immediately caught two bugs in the new system. That’s not failure. That’s the design working exactly as intended.

Five PRs in one day: #719, #723, #721, #724, #725. Together they close the epic and demonstrate why the deterministic-first pattern lets you replace a live system without a transition period.

The never-block contract: LLM outputs are advisory only. They never block the primary CI decision. If the LLM crashes, times out, or hallucinates, the deterministic verdict posts unchanged and the rest of the pipeline runs as if the LLM step never existed.

The two contracts that matter

The pre-screen workflow lives on two non-negotiable contracts that separate the product from the polish.

The first: the deterministic classifier is the product. It ingests validator JSON output, applies 12 rules to the changeset, and emits a verdict — PASS, CHANGES_REQUESTED, or HARD_BLOCK. Three outcomes. No gray. No ambiguity.

The classifier is a pure function. No I/O. No dependencies beyond the Python stdlib. Every test case maps to a rule. Every rule maps to observable, repeatable behavior. You can trace it from input to output without waiting for an API to respond or hoping an LLM doesn’t hallucinate.

PR #719 closed this layer in 579 new lines: .github/workflows/pr-prescreen.yml (~270 lines of workflow), scripts/pr-prescreen/classify.py (the classifier), and 12 unit tests covering every rule and edge case.

The workflow pattern is fork-safe: pull_request_target, SHA-pinned checkout, persist-credentials: false, never executes PR-controlled code. I copied the security pattern verbatim from the broken Gemini workflow (lines 23-79 — those were the load-bearing security). The security model didn’t change. The signal source did.

The second contract: the LLM is advisory, never blocks. When the deterministic layer says PASS, the Groq LLM generates a 5-line human-readable summary. The summary is rendered as a GitHub comment. It carries zero veto power.

If Groq times out, crashes, the API key leaks, or the model hallucinates — continue-on-error: true on the workflow step ensures the pre-screen verdict still posts. The comment just doesn’t appear. Slack doesn’t ping a summary. The rest of the CI runs unchanged. The primary signal is independent of the advisory layer.

The verdict table:

Groq runs only on PASS verdicts. If Groq fails, the verdict still posts — just without the summary. The deterministic layer is the contract. The LLM is the enhancement that runs inside the bounds of the contract.

PR #723 added the Groq integration: 388 new lines, scripts/pr-prescreen/summarize.py. It calls Groq directly via stdlib urllib — no SDK, no dependency overhead, no transitive vulnerability surface. Model: llama-3.3-70b-versatile. Wall-clock budget: 5 seconds. Single attempt. No retries.

The function is dead simple: POST the verdict JSON plus the changeset summary to Groq, parse the response, format it, return. 11 unit tests including fixes from PR #720’s review:

• broad except Exception for the never-block contract — catch literally everything
• OSError instead of TimeoutError for broader I/O coverage (socket.timeout, connection resets, the rest of the network failure surface)
• json.JSONDecodeError guard for malformed responses

One tested invariant matters most: user-controlled PR content cannot override the fixed system prompt. The system prompt is a string literal in the source. The PR body is data. They never meet in the same code path. The classifier output goes into the user-role message; the system role is hard-coded and unreachable from outside.

What “never block” buys you

The old Gemini system gave an LLM veto power over 3,000+ shipped artifacts. Every time it broke, you couldn’t delete it — too much workflow depended on it staying alive. The downstream blast radius made retiring it a multi-week migration.

You’re stuck in maintenance mode: tuning prompts, chasing API changes, hoping the next model version handles the job the same way the last one did. You can’t turn it off. You can’t replace it. The veto power is a cage.

The never-block contract changes the trade-off entirely. The LLM is an enhancement layered on top of a deterministic core, not the core itself. If it malfunctions, the workflow degrades gracefully to the deterministic verdict — which you already trust to be correct.

You can replace the old system on the same day you deploy the new one. You’re not hedging bets. You’re not running both in parallel. You’re not waiting for three weeks of production data to prove the new system is safe. You measure trust against the deterministic layer; the LLM is polish that can’t revoke the decision.

PR #719 merged. The next day PR #721 deleted gemini-code-review.yml (179 lines of perpetually broken YAML) as a single breaking change.

That PR removed:

• the workflow file itself
• the orphaned ENABLE_GEMINI_REVIEW repo variable (operator deletes after merge)
• the --thorough flag on the validator (advertised in the README but with broken plumbing)

It also added two new surfaces:

• scripts/pr-prescreen/audit.py — appends one row per pre-screen run to freshie/inventory.sqlite, tracking the decision history for post-mortems and operator review. Inline CREATE TABLE IF NOT EXISTS schema. continue-on-error: true so DB failures don’t mask the primary signal.
• a 265-line operator runbook at 000-docs/265-DR-GUID-pr-prescreen-system.md documenting the workflow, the verdicts, the audit schema, and the operator’s playbook.

No transition period. No parallel runs. No “let’s keep both for safety.” The new system had been live for exactly one workflow_dispatch manual invocation. That was enough to trust it — because the deterministic layer is the contract and it’s testable end-to-end without the LLM in the loop.

First live invocation found two bugs

The first production run was PR #722 — a hyperflow submission from an external contributor with 8 new skills. The run immediately surfaced two design flaws the test suite didn’t catch, because the test suite ran against toy data and missed the production edge cases.

Bug 1: empty-changeset explosion. PR #722 touched sources.yaml only — no plugins/ paths. The changeset filter triggered a fallback I’d written without thinking: “no plugin paths matched” → pass through all results → generate comment body for ~400 skills.

GitHub’s comment API caps bodies at 65,536 characters. The post failed silently. The deterministic verdict was correct, but the comment never landed and the Slack ping fired with an incomplete reference. Confusing signal to the operator. Real production bug caught by the first real-world input.

Bug 2: pointless comments. Even after fixing Bug 1, every infrastructure or documentation PR would still get a “PASS: no plugin paths matched” comment. That’s accurate — nothing happened. But it’s signal without value: visible noise on every non-plugin PR. Noise erodes signal over time. After a week, the operator stops reading the comments.

PR #724 fixed both in 50 lines net (+50/-163 after deleting the dead fallback). Three changes:

• Empty changeset → emit empty filtered list (the classifier reports “no plugin paths,” doesn’t dump everything).
• Skip the Post Comment and Slack Notify steps entirely when steps.diff.outputs.count == '0'.
• Cap the per-skill table at 100 rows and truncate the body to 65,000 characters with a clear marker.

Empty changeset → no comment, no ping. The deterministic signal has preconditions. When those preconditions aren’t met, the system stays silent. No noise. No confusion.

The system found its own design flaws on first contact with reality. That’s not a weakness of the never-block contract — that’s the whole point. The deterministic classifier is safe enough to trust on its first invocation. The advisor runs under safe conditions. When reality violated the conditions, the system degraded gracefully and the operator fixed the precondition. Not the core logic. The core logic was never wrong. The assumptions feeding it were.

The spec was invisible — fix the surface

PR #722 was thoughtful. The contributor read CONTRIBUTING.md, followed the issue template, and wrote skills that made technical sense. All 8 were structurally sound. And all 8 were missing every one of the 6 marketplace-required frontmatter fields plus every one of the 7 body sections.

The expectations were buried in 000-docs/6767-b-SPEC-DR-STND-claude-skills-standard.md — the Global Master Standard for Claude Skills, v3.6.0, with the 100-point rubric and source citations against Anthropic + AgentSkills.io. Authoritative. Comprehensive. Invisible to contributors.

No link from the PR template. No mention in CONTRIBUTING.md. No signpost in the plugin-submission issue template. The deterministic classifier caught it all as D and F grades and reported each one. That’s correct — the validator is working. But the feedback loop was broken: the spec was invisible to contributors. Invisible requirements produce work that looks wrong until you read the fine print. By then you’ve already written it.

PR #725 surfaced the spec on three contributor surfaces:

• CONTRIBUTING.md — new “Read the spec before you start” callout above “Before You Submit,” with the distilled requirements and direct links.
• .github/PULL_REQUEST_TEMPLATE.md — top-of-template now points to CONTRIBUTING and to the spec. Also replaces stale “auto-review bot” phrasing that referred to the deleted Gemini workflow.
• .github/ISSUE_TEMPLATE/plugin-submission.yml — adds a markdown description block with the spec callout and replaces 5 generic checkboxes with 7 spec-aware ones covering the real validator gates.

Also corrected two stale strings while I was there: “Gemini 2.5 Pro will post a review” → “the PR Pre-screen workflow,” and the example switched from the deprecated --enterprise flag to the current --marketplace flag.

The validator still grades the same way. The standard didn’t move. But now the spec isn’t a surprise buried 8 directories deep; it’s the first thing you see when you open a pull request. The expected drop in D/F submissions isn’t a change to the validator. It’s a change to the surface contributors actually touch.

The five-PR arc — #719, #723, #721, #724, #725 — is a case study in what never-block lets you do: ship something small, watch it collide with reality, and fix the collisions without unwinding the core. The deterministic classifier didn’t change between Phase 1 and the hot-fix. The Groq advisory didn’t change either. The preconditions and the surface visibility did, because reality demanded it.

Deterministic first, LLM second, never-block contract always. That’s the formula that lets you retire the old system on the same day and trust the replacement.

You get a file hash and a Merkle proof that claims it’s anchored in some blockchain transaction. How do you verify that claim without trusting the service that gave you the proof?

I built ProofLedger to create these proofs, but the verification should work independently. Anyone can validate a Merkle proof with the right algorithm. Here’s how to walk up the tree from leaf to root.

What’s Actually in a Merkle Proof

A Merkle proof is a list of sibling hashes that lets you reconstruct the path from your file’s hash up to the Merkle root. Each step combines your current hash with a sibling hash to produce the parent hash.

The proof tells you two things for each step:

• The sibling hash (as a hex string)
• Which side to put it on (“left” or “right”)

# Example proof structure
proof = {
    "hash": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
    "merkle_path": [
        {
            "hash": "b5d4045c3f466fa91fe2cc6abe79232a1a57cdf104f7a26e716e0a1e2789df78",
            "position": "right"
        },
        {
            "hash": "c3d4045c3f466fa91fe2cc6abe79232a1a57cdf104f7a26e716e0a1e2789df79",
            "position": "left"  
        }
    ]
}

That’s it. No magic, no proprietary formats. Just a starting hash and a list of directions.

The Hash Combination Algorithm

Each step up the tree combines two 64-character hex strings into one. The critical part is getting the concatenation order right.

import hashlib

def combine_hashes(left_hex, right_hex):
    """Combine two hex hashes into their parent hash."""
    # Concatenate the hex strings
    combined_hex = left_hex + right_hex

    # Convert to bytes, then hash
    combined_bytes = bytes.fromhex(combined_hex)
    parent_hash = hashlib.sha256(combined_bytes).hexdigest()

    return parent_hash

# Example
left = "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
right = "b5d4045c3f466fa91fe2cc6abe79232a1a57cdf104f7a26e716e0a1e2789df78" 
parent = combine_hashes(left, right)
print(f"Parent: {parent}")

The order matters. combine_hashes(A, B) produces a different result than combine_hashes(B, A). That’s why the proof needs to specify position.

Walking the Full Path

Now you can iterate through the proof steps. Start with your file hash. At each step, combine it with the sibling hash in the specified position.

def verify_merkle_proof(file_hash, merkle_path):
    """Walk up a Merkle tree and return the computed root."""
    current = file_hash.lower()  # Normalize to lowercase

    for step in merkle_path:
        sibling = step["hash"].lower()
        position = step["position"]

        if position == "left":
            # Sibling goes left, current goes right
            current = combine_hashes(sibling, current)
        else:
            # Current goes left, sibling goes right  
            current = combine_hashes(current, sibling)

        print(f"Step: {current}")

    return current

# Test with our example proof
file_hash = "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
merkle_path = [
    {
        "hash": "b5d4045c3f466fa91fe2cc6abe79232a1a57cdf104f7a26e716e0a1e2789df78",
        "position": "right"
    },
    {
        "hash": "c3d4045c3f466fa91fe2cc6abe79232a1a57cdf104f7a26e716e0a1e2789df79",
        "position": "left"  
    }
]

computed_root = verify_merkle_proof(file_hash, merkle_path)
print(f"Computed root: {computed_root}")

The function returns the root hash. That’s what should match the value stored on-chain.

Complete Verification Function

Here’s a complete verifier that handles the proof structure and validates the result:

import hashlib
import json

def hash_file(filepath):
    """Generate SHA-256 hash of a file."""
    sha256_hash = hashlib.sha256()
    with open(filepath, "rb") as f:
        for chunk in iter(lambda: f.read(4096), b""):
            sha256_hash.update(chunk)
    return sha256_hash.hexdigest()

def verify_proof(file_path, proof_data):
    """Verify a complete Merkle proof against a file."""
    # Hash the file
    file_hash = hash_file(file_path)

    # Extract proof components
    claimed_hash = proof_data["hash"]
    merkle_path = proof_data.get("merkle_path", [])

    # Verify file hash matches claim
    if file_hash != claimed_hash.lower():
        return {
            "verified": False,
            "error": f"File hash {file_hash} doesn't match claimed {claimed_hash}"
        }

    # If no merkle path, just verify the hash
    if not merkle_path:
        return {
            "verified": True,
            "file_hash": file_hash,
            "merkle_root": file_hash  # Root is just the file hash
        }

    # Compute the Merkle root
    computed_root = verify_merkle_proof(file_hash, merkle_path)

    return {
        "verified": True,
        "file_hash": file_hash,
        "merkle_root": computed_root,
        "path_length": len(merkle_path)
    }

# Usage
with open('proof.json', 'r') as f:
    proof = json.load(f)

result = verify_proof('document.pdf', proof)
print(json.dumps(result, indent=2))

Why This Matters for Evidence

You don’t need to trust the timestamping service. The Merkle proof lets you independently verify that your file hash was included in the transaction. You can check the blockchain explorer yourself to confirm the root hash exists on-chain.

The proof can’t be forged after the fact. If someone tries to create a fake proof for a file that wasn’t actually anchored, the computed root won’t match what’s on the blockchain.

For legal or forensic use, this means opposing counsel can verify your evidence timestamps independently. They don’t have to trust ProofLedger, ProofAnchor, or any other service. They just run the algorithm against the blockchain data.

That’s the point of cryptographic proofs. Math, not trust.

Programmer, Coder, Developer. I’ve always believed that every developer has an origin story. Some people discover coding in a college course, some stumble into it through a job, and some — like me — were simply destined to become nerds from the start.

My journey into programming began in the early 1980s, long before sleek laptops, cloud IDEs, or AI‑powered anything. Back then, computers felt mysterious and a little magical. They hummed, they beeped, they had screens that glowed in a way that made you feel like you were peeking into the future. And for me, that future started with MS‑DOS and a blinking cursor.

The First Program I Ever Wrote

I still remember typing out my first lines of BASIC. It wasn’t anything groundbreaking — just a simple program that printed text on the screen — but the moment I hit Enter and watched the computer do something because I told it to, I was hooked.

There was no Stack Overflow. No YouTube tutorials. No ChatGPT or Copilot to bail you out. Just trial, error, and the thrill of making something work. I didn’t know it then, but that little program was the spark that would shape my entire career.

HTML: The Language of The Web

Fast‑forward to college life. The World Wide Web was exploding with a new tool that was used browse the web called Netscape, and suddenly everyone wanted a website. When I discovered HTML, it felt like BASIC all over again — but this time, what I built could live on the internet for the world to see.

I loved everything about it. The tags, the structure, the way a few lines of code could transform into something visual. I’d stay up late building pages, tweaking layouts, experimenting with colors, and breaking things just to figure out how to fix them.

That passion for building and creating webpages became the foundation of my career. It wasn’t just coding — it was storytelling, design, logic, and creativity all rolled into one.

Falling Down the Developer Rabbit Hole

Once you learn one language, you start to see the patterns. And once you see the patterns, you want to learn more…

So I did.

JavaScript came next — back when it was still the wild west of pop‑ups, mouse trails, and “DHTML.” Then came PHP, SQL, React, Python, and a handful of others I picked up along the way. Each one opened a new door. Each one taught me a new way to think.

And each one reminded me that in tech, the learning never stops.

The Challenge No One Warns You About

If there’s one struggle that’s followed me throughout my journey, it’s this:

Just when you finally master a language… it becomes outdated.

I’d spend months learning a framework, getting comfortable, building real projects — and then suddenly the industry would shift. A new version would drop. A new “must‑learn” tool would appear. Great, so now I have to learn this new language: wha-who-where-huh.wtf!?

Some weeks it felt like programming languages were being released faster than I could install them.

At first, I saw this as a personal failing. Why couldn’t I keep up? Why did everything I learned seem to expire so quickly? Why did the tech world move at a pace that felt impossible to match?

But over time, I realized something important:

The goal isn’t to keep up with everything — it’s to stay curious.

Once I embraced that, everything changed.

What I Learned Along the Way

Looking back, here are the lessons that have stuck with me the most:

1. Your first language matters — not because you’ll use it forever, but because it teaches you how to think.
   BASIC didn’t follow me into adulthood, but the logic it taught me did. Loops, conditions, structure — those fundamentals never go out of style.

2. The web is always evolving, and that’s a good thing.
   HTML in the 90s was simple. Today it’s part of a massive ecosystem. That growth is what makes this field exciting. If things stayed the same, we’d all be bored.

3. You don’t need to learn every new language.
   Seriously. You don’t. Pick the ones that align with your goals. Learn enough to stay relevant, not enough to burn out.

4. Curiosity beats mastery.
   Mastery is temporary. Curiosity is renewable. The developers who thrive aren’t the ones who know everything — they’re the ones who stay open to learning.

5. Your journey is uniquely yours.
   Some people start coding at 12. Some start at 40. Some love backend logic. Some love frontend design. Some love both. There’s no “right” path — only your path.

Why I Still Love This “Work”

Even after all these years, I still get that same spark I felt back in the 80s when I typed my first BASIC command. Technology has changed, but the feeling hasn’t.

I love the puzzle‑solving.
I love the creativity.
I love the moment when something finally works after hours of debugging.
I love that the web is still a place where anyone can build something from nothing.

And I love that, in a field that evolves constantly, there’s always something new to learn — not because you have to, but because you get to.

And The Journey Continues…

If there’s one thing I hope readers take away from my story, it’s this:

You don’t need to be the fastest learner or the trendiest developer. You just need to stay curious, stay persistent, and stay excited about what you’re building.

The tools will change.
The languages will change.
The frameworks will definitely change.

But the joy of creating something from scratch — that never goes away.

And that’s why, after all these years, I’m still proud to call myself a web nerd!

If you’ve been writing software for a few years, you eventually start designing for change.

A content delivery system: a new format will appear, a new player will appear, so let’s not hard-code formats. An e-commerce site: a new payment method will be requested, so let’s not hard-code billing logic. A document pipeline: a new processing engine will appear, so let’s not hard-code engines.

This is good instinct. You read books like Analysis Patterns, you internalize the idea that the model should be flexible, you push concrete decisions out of code and into data. New format? Insert a row. New payment? Insert a row. New engine? Insert a row.

It’s a beautiful pattern. It really does extend the lifespan of a system.

But after enough years of running systems built this way, here’s the part that doesn’t show up in the books:

Dynamic isn’t enough. Operations is the other half — and that other half is usually paid by someone else.

The “wait, maybe…” moment

Reality always overshoots the model. Always.

You build a content system that handles formats dynamically, and then someone asks for a format whose delivery rules don’t fit the existing shape. You build a payment system that takes new methods through configuration, and then someone wants a billing model where the “amount” isn’t even computed at the same time as the “charge.” You build an engine registry, and then a new engine doesn’t conform to the lifecycle every other engine has assumed.

Each time, the moment looks the same. You stare at the request, and your first thought is: that’s outside the model. And your second thought, a few minutes later, is:

Wait, maybe… if I interpret this field a little differently, and if I add one column here, and if I let this branch handle a special case… it fits. Sort of. It doesn’t break anything.

So you do that.

The system keeps running. No downtime. No coordinated migration. No painful conversation with the integration partners. From your seat as the designer, the dynamic structure absorbed the change. The pattern worked.

That’s the part designers love. That’s the part that gets written about.

Who pays for the other half

Here’s what’s harder to see from the designer’s seat: every “wait, maybe…” moment leaves a small residue somewhere in operations.

The operator now has to remember that for this particular case, the workflow is slightly different. The reporting tool needs a footnote. The on-call playbook gets one more conditional. The next person to onboard needs another paragraph of context. The integrating system has to send a value in a slightly unexpected place.

None of these are catastrophic. None of them break the system. Each one, on its own, is a small inconvenience.

But the small inconveniences accumulate. And the people accumulating them are usually not the people who designed the dynamic structure in the first place.

The designer experiences each “wait, maybe…” as a successful absorption. The operator experiences it as one more thing to remember. Same event, two ledgers. Only the designer’s ledger gets reviewed.

This is where engineering satisfaction can become quietly self-serving. The system didn’t break. The pattern held. Therefore the design is good — except good for whom, exactly?

The road I didn’t take

There is, of course, an alternative. You can stop the system, ship version 2, ask everyone to migrate, and start clean.

A scheduled 24-hour outage. A v2 documentation packet sent to every integrating partner. A coordination meeting. A cutover.

I have, for twenty-four years, mostly chosen not to do this. I have preferred quiet absorption — interpretation, gentle reshaping, “wait, maybe…” — over coordinated rebuild.

Whether that was right, I genuinely don’t know. There were probably operators along the way who would have been happier with one painful migration than with years of small accommodations. There were probably integrating systems whose engineers would have preferred a clean v2 over a v1 that kept quietly bending.

I chose to keep the shape. That choice has a cost. The cost is paid in operator-hours, in playbook footnotes, in the small extra cognitive load of working with a system that has absorbed more than its original model anticipated.

I’m not saying I was wrong. I’m saying: I’m still not sure.

Generic underneath, specific on top

There’s one thing I do believe, with more confidence than the rest:

When the model gets very generic, the UI usually has to get very specific to compensate.

A maximally flexible data model — the kind that absorbs new formats, new payment methods, new engines — is, almost by definition, awkward to interact with directly. Direct interaction with a generic model means the human has to supply all the missing context. That’s exhausting.

The good outcome is: the model stays generic underneath, and the UI is built specific to each use case on top. Each surface is custom. Each surface is rigid in exactly the way that makes it usable.

This is a hard decision to make, because every specific UI you build feels temporary. You’re going to throw it away when the use case shifts. You build it knowing it has a shorter half-life than the model below it. That asymmetry is uncomfortable.

But I think the discomfort is the right discomfort. A long-lived generic core, with shorter-lived specific surfaces on top, is — based on what I’ve watched survive over twenty-four years — closer to how systems actually age well.

Three observations

None of these are conclusions:

1. Dynamic structure extends a system’s life. It does not, on its own, make operating that system pleasant.

2. Every “wait, maybe…” absorption is a real engineering achievement and a small tax on someone downstream. Both of these are true.

3. If you make the model very generic, give the operators a UI that isn’t generic.

Dynamic isn’t enough. Operations is the other half — and that other half is usually paid by someone else.

After twenty-four years of this, that’s the only thing I feel sure of.

Earlier in this series:

• The Accordion Pattern: Why I stopped writing one fat LLM prompt
• Nobody knows when a job will finish. I’d still like to report it accurately.
• What survives when you build alone for 24 years.

Every senior delivery manager I have ever known has the same career anecdote. They have never, across some round number of years, watched a major release ship on the date set at kickoff. Not once. They will say this with a kind of dry resignation, in the same tone people use to describe the weather. It is the universal experience of running software projects, and it is the universal experience of running them in companies that produce software for a living.

I want to take that observation seriously rather than file it under “project management is hard.” If something happens consistently across forty years, across sectors, across team sizes, across methodologies that openly disagree about almost everything else, that is not a series of unfortunate local failures. It is a structural feature of how the industry runs. The interesting question, the one this piece is about, is not why deadlines slip. The data on that is settled. The interesting question is why the deadline ritual continues to be performed exactly the same way despite the data being settled.

The data, briefly

The numbers are easy to find and have not improved in any direction that matters in twenty years.

BCG’s 2024 study, “Most Large-Scale Tech Programs Fail: How to Succeed,” reports that more than two-thirds of large-scale technology programs fail to deliver on time, on budget, or to scope, and that the share of programs failing on all three has been roughly constant for a decade. The Standish Group’s CHAOS Report, in its 2020 edition, put the breakdown at 31% successful, 50% challenged, and 19% outright failed — and Standish then announced it would stop publishing the report on the grounds that nothing was changing and the act of publishing it had stopped being useful. The miss rate has been measured, restated, benchmarked across tens of thousands of projects, and the consistent finding is that the deadline-promising ritual produces predictable misses on a predictable schedule.

This is not a team-specific failure. It is the industry’s running average. Any given project is, by historical baseline, more likely to slip than to ship.

The four mechanisms behind the miss

Practitioners who have run a few hundred projects describe four mechanisms that, between them, account for almost every miss they have personally watched.

The first is requirements churn. Pretty much no project survives the journey from kickoff to release without absorbing changes the team did not anticipate. A stakeholder sees a draft mockup and realises they meant something else. A regulator publishes a new rule mid-build. A competitor ships a feature that becomes a must-match. The pattern in mid-sized projects is something like three to five serious scope shifts during a six-month build. Estimates given at kickoff are not estimates of the project that will eventually ship. They are estimates of a project that no longer exists by week three.

The second is hidden complexity. The first integration with a third-party API turns out to be against documentation that was written eighteen months ago and is no longer accurate. A legacy table in the data warehouse has six edge cases nobody flagged at design time. A “trivial” auth flow has a quirk that surfaces on the seventh week of the build. There is a documented pattern, repeated across delivery managers, of integration estimates that come in two to four times larger than the kickoff number — not because the team underestimated the integration but because the integration’s actual surface area was not visible from the outside until the team was already in it.

The third is the planning fallacy. The cognitive bias has a name and a citation. Daniel Kahneman and Amos Tversky introduced it in 1979 in “Intuitive prediction: Biases and corrective procedures,” describing the universal human tendency to underestimate the time, cost, and risk of future tasks even when the same person, in the same domain, has documented evidence that prior tasks took longer than predicted. The bias is robust across cultures and disciplines. Experienced engineers are no less susceptible than first-year ones; the experiment was repeated through the 1990s and 2000s with the same result. The mind, when planning, takes an inside view of the task — the specifics of this case, this customer, this codebase — and systematically discounts the outside view that asks how similar tasks have actually played out historically.

The fourth is the keyboard-time-versus-cycle-time confusion. When an engineer says “this will take three days,” they almost always mean three days of focused implementation. The release calendar pays for the entire task lifecycle: design review, code review, revisions, test runs, integration tests, environment provisioning, deployment, stakeholder demo, customer feedback, fixes, redeploy. A commonly-cited rule of thumb among delivery managers is that pure coding time is roughly 30 to 40 percent of the total task duration. The team is not wrong about the coding. The team is being asked to predict the lifecycle and pricing only the part of it they directly control.

Hofstadter’s Law — it always takes longer than you expect, even when you take into account Hofstadter’s Law — was published in 1979, the same year as the planning-fallacy paper, in Gödel, Escher, Bach. Software’s main contribution to the literature in the half-century since has been to confirm both findings.

The honest practice already exists

What is striking about all of this, on close inspection, is that the working version of estimation is not unknown. Senior delivery managers, when they have the latitude, do exactly the same handful of things.

They decompose work into chunks of one or two days, because the planning-fallacy literature is clear that estimates on small chunks aggregate more accurately than estimates on the same body of work made in one large breath. They quote ranges instead of points: not “three weeks” but “two to four weeks, with a P50 of 2.5 and a P90 of 4.” They itemise risks as separate line items rather than burying them inside a padded estimate, on the principle that a risk that is named can be retired and a risk that is hidden cannot. They keep a rolling forecast, updated weekly or per sprint, on the basis that a week of actual data is worth more than any number of pre-kickoff predictions. Mature teams keep an internal log of past estimates against past actuals and derive a multiplier for their own work; the multiplier is reportedly stable around 1.7 to 2.0 in delivery groups that track it consistently.

None of this is new. None of this requires new tooling. The Project Management Institute has been describing variants of this practice in its body of knowledge since the 1990s. The agile literature describes essentially the same approach in different vocabulary. There is no estimation-method gap.

So why the single date

The interesting question is what the single date is doing in the room at all, given that everyone competent who has worked on the problem agrees the single date is wrong.

The single date is doing a social job, not a forecasting one. A range with risk lines makes the team’s uncertainty visible to the customer, the executive, the board. It says, in writing: we do not know yet. Most organisations, by their cultural physics, find that statement intolerable. The customer asks “when will it be ready?” and the political reflex is to give them a number. The executive asks the project manager to commit. The project manager commits to a date that nobody in the room actually believes. The build runs, the date misses, the team takes the heat, and the next project starts the same conversation in the same language.

This is not the engineers’ fault, and it is not the project managers’ fault, and it is not even the executives’ fault in any meaningful sense. It is the standing trade-off the field has chosen: a comforting fiction at kickoff, paid for at the end in slippage costs, blame, and burned-out teams. The data on slippage rates is forty years old, and it has stayed flat through every methodology that promised to fix it, because the methodology has never been the problem. The approaches that try — the ones that ask the customer to absorb uncertainty in writing, up front — get adopted in pockets, and almost never spread outside organisations whose senior leadership has personally chosen to treat estimation as a probability problem.

The 2026 AI footnote

By 2026 most major issue trackers ship some form of AI-assisted estimation. They look at the team’s historical data, recognise patterns, flag anomalies, and produce probability distributions instead of single numbers. Industry coverage of McKinsey-cited research reports that ML models trained on a team’s own delivery history produce estimation accuracy improvements of roughly 20 to 30 percent over expert-only estimates, which is real but should not be oversold. The AI does the part of the job the literature already knew how to do. It does not change the social transaction. The customer still asks for a single date; the system records the distribution’s mean; the dashboard shows the comforting number; the political incentive is unchanged. The tools improve the input. The conversation that consumes the input is the same conversation it has been since 1979.

Why nobody seems to mind

The honest answer is that the deadline ritual is, for most stakeholders, not actually about deadlines.

It is about commitment theatre. The customer wants to feel that the supplier is taking the work seriously. A confident date communicates seriousness in a way that a probability distribution does not. The supplier wants to feel that the customer is committed enough to the work to be told a date in the first place. The PMO wants a clean Gantt chart for the board deck. The board wants the Gantt chart to be green. The team wants the executive to stop asking. Everyone in the system has a small, local, rational reason to prefer the comforting number, and the system as a whole pays for those small rational preferences with two-thirds of large programs missing on time, budget, or scope.

The miss is not a bug. The miss is the price the system has decided to pay for the comfort of the kickoff conversation. Forty years of data suggest the price is stable.

What an honest practice would look like

A team that wanted to break the pattern, on a single project, could do exactly what the senior delivery managers already know how to do. Decompose to small chunks. Quote a range, not a point. Itemise risks. Update the forecast every week. Keep a journal of estimates versus actuals and let it train the next round. Tell the customer the truth: that ranges land more often than dates do. The data on the practice is good. The practice is not the obstacle.

The obstacle is what happens in the meeting where the customer says “yes, but when?” — and somebody in the room has to decide whether to say a number that the team does not believe, or to insist on a probability distribution and absorb the social cost of doing so. That moment is the entire problem, and it is reproduced, in roughly the same form, in every kickoff meeting in the industry, every week.

The ritual

The deadline ritual will keep producing the deadline outcome for as long as the social cost of “I do not know yet” exceeds the political cost of being wrong six months later. That is not a project-management problem. That is the field’s standing trade-off, and the field has been making the same trade for forty years.

The data is not the problem. The methods are not the problem. The estimation literature is not the problem. The problem is that the room does not, when push comes to shove, want to hear a probability distribution. The room wants a date, accepts the date, and treats the slippage as a discrete misfortune rather than the rate the system was always going to produce. As long as that remains the standing arrangement — and it has remained the standing arrangement through every wave of “this methodology will fix it” — every project will keep shipping late, every senior delivery manager will keep collecting the same anecdote, and the next kickoff will keep asking the same question and getting the same answer, in the same tone, from the same people who already know better.