When engineering leaders approach product managers or executive stakeholders demanding time to fix “technical debt,” they are frequently met with blank stares or polite deferrals.

To the business, an engineered refactor that results in zero visible feature changes looks like a massive waste of capital. If you cannot explain the real-world operational impact of your code liabilities in terms of time and money, you will never secure the sprint capacity necessary to fix them.

The Reality of System Drag

Technical debt behaves exactly like credit card debt. It provides a brief injection of speed upfront—allowing a team to skip edge-case handling or cut architectural corners to hit a critical market deadline—in exchange for a compounding interest rate down the road.

That interest rate manifests as pure system drag:

• Development cycles start taking twice as long.
• Production regressions skyrocket out of nowhere.
• Your elite engineering team spends all day manually triaging bugs instead of building revenue-driving features.

When the interest outpaces your output, your feature velocity drops to zero. You are officially paying only the interest on your debt, completely unable to touch the principal.

The Friction Matrix: Interaction vs. Blast Radius

To fix the communication gap between product management and engineering, you need to strip away emotional complaints (“this code is messy”) and replace them with two basic, non-technical metrics: How often do we touch it? and How bad is it if it breaks?

1. Likelihood of Interaction

How frequently does your team actually modify, extend, or deploy code in this specific domain?

• A poorly written legacy batch script that runs once a quarter and requires no maintenance is a low-traffic zone. You can safely ignore it.
• A messy, tightly coupled payment routing module that teams have to modify every single week is a high-traffic hazard.

2. Severity of Blast Radius

If this component suffers a critical failure in production, what is the scope of the damage?

• Does a bug here bring down the entire user login and checkout pipeline? That is a catastrophic blast radius.
• Or does it simply cause a visual rendering bug on an internal settings dashboard that nobody looks at? That is a minor inconvenience.

When you look at debt through this lens, prioritization becomes incredibly obvious. You stop wasting hours rewriting harmless legacy code and focus exclusively on the high-traffic, high-damage hazards that are actively threatening the business.

Translating Debt into Boardroom Reality

When you present technical debt to non-technical leaders using this risk framework, the conversation shifts instantly. You are no longer asking for permission to “clean up the codebase.” You are presenting an explicit risk mitigation strategy.

Instead of saying:

“We need two sprints to rewrite the database extraction layer because the code is messy and hard to read.”

You present the data-backed reality:

“Our database extraction layer is our highest-traffic system component, and its current limitations are putting a 35% time penalty on every single feature we try to ship. Spending two sprints here clears this bottleneck and reclaims that lost team capacity.”

The Technical Debt Ledger is Your Shield

Elite engineering governance requires an active, living registry. By institutionalizing a lean technical debt ledger, technical leaders gain an unshakeable map of their systemic liabilities. It stops subjective arguments, removes emotion from sprint planning, and ensures that every engineering hour spent refactoring delivers undeniable business value.

👉 Secure your copy of The Lean Technical Debt Ledger on Gumroad today and clone the framework straight into your workspace.

Architect Forward and Transform.

When engineering teams double or triple in size, their single greatest points of failure shift away from raw computing complexity toward institutional amnesia. Critical engineering architecture shifts occur during casual Slack conversations, emergency Zoom triage rooms, or quick GitHub pull requests. Without structure, the contextual boundaries behind those design iterations evaporate.

The Cost of Historical Amnesia

Consider a standard engineering crossroad: an engineering squad swaps out a highly synchronous HTTP communication channel for an asynchronous architecture powered by AWS SQS. At the time, the decision makes perfect sense—the payload processing volumes required decoupling to isolate resource exhaustion. However, two years later, during a major microservice migration, a new senior engineering hire observes the layout and brands it an overly complex architectural anti-pattern.

Without an unshakeable audit trail, the new team spends months refactoring the asynchronous pipeline back into a synchronous flow, only to inevitably hit the exact same structural walls that the original team defeated two years prior. This circular cycle represents a massive loss of capital, a catastrophic blow to morale, and a critical structural failure known as Technical Amnesia.

Applying Blast Radius to Architectural Choice

To fix this, technical leaders must introduce a lightweight framework that segregates decisions by risk and reversibility. We achieve this by mapping the classic corporate governance models into system choices: Type 1 and Type 2 decisions.

1. One-Way Doors (Type 1 Decisions)

If you walk through the door, you cannot easily walk back. Swapping your primary database from PostgreSQL to DynamoDB, altering data residency protocols to meet strict compliance mandates like SOC2, or redesigning the core billing logic fall squarely into Type 1. These require heavy internal transparency, comprehensive validation, and mandatory logging in a record.

2. Two-Way Doors (Type 2 Decisions)

Choosing a specific logging package, establishing variable naming styles within a localized module, or selecting a front-end UI visual library are low-impact items. These shouldn’t face layers of committee approvals. Teams must execute Type 2 choices immediately to keep engineering velocity at its peak, logging them in a quick, two-line lean registry for future reference.

Implementing the Lean ADR Workflow

An Architecture Decision Record (ADR) should never read like an academic thesis. It is a lean, highly specific document. To succeed operationally, every record must capture exactly four core dimensions:

• Context: What real-world technical or business operational constraint forced this choice? What structural limitation did we encounter?
• Decision: What is the concrete, active technical step we are taking? Is it a Type 1 or Type 2 door?
• Consequences: What do we give up? (Every true architectural choice is a trade-off. If your ADR lists zero downsides, you haven’t thought deeply enough about the architecture).
• Status: Is this actively Proposed, Accepted, or has it already been Superceded by a subsequent design record (ADR-n > ADR-current)?

Strategic Alignment from the Code to the Boardroom

By forcing your engineering squads to maintain a clean, centralized ADR registry, you build a protective perimeter around your system velocity. New senior engineers get up to speed in days because they can read the chronological history of the system layout from ADR-001 to the present. More importantly, when executive leadership or external auditors question technical infrastructure shifts, you don’t offer vague hand-waving—you provide a transparent, high-context operational map.

Governance shouldn’t be a bureaucratic bottleneck. When done cleanly, lean governance is the ultimate accelerator.

👉 Secure your copy of The Architecture Decision Record Log on Gumroad today and clone the framework straight into your workspace.

Architect Forward and Transform.

When engineering reality fails to translate into boardroom language, the organization grinds to a halt in two specific, highly destructive ways:

• Analysis Paralysis: Critical architectural decisions stall indefinitely because stakeholders don’t understand the technical trade-offs.
• Invisible Technical Debt: High-risk code liabilities quietly accumulate behind the scenes until they inevitably tank your team’s feature delivery speed.

If you want to protect your system from catastrophic technical debt while supercharging your engineering velocity, you don’t need more meetings. You need operational structure. You need a system that balances strategic direction with true operational liability.

The Cost of “Historical Amnesia”

Think about the last major architectural decision your team made. Where is it documented? Is it buried in a dead Slack thread? Stale Confluence pages? Or worse, does it only live inside the heads of two senior developers who might leave next quarter?

When systems grow without a unified governance framework, companies suffer from historical amnesia. Two years from now, when you bring on new senior hires, they will waste weeks trying to reverse-engineer why your infrastructure was built a certain way.

True governance isn’t about red tape or slowing down development. True governance is about creating clean context—building a living ledger of your technical choices so your team can move fast without breaking the foundations.

Introducing the Scaling Engineering Governance Pack

To bridge the gap between deep infrastructure planning and executive visibility, we built The Scaling Engineering Governance Pack.

Crafted directly inside Notion, this is a production-ready, highly modular command center designed to give engineering leaders a unified executive cockpit. It brings your strategic roadmap and your active system risks into a single, scannable lens optimized beautifully for both desktop and mobile layouts.

Here is how the framework transforms your engineering operations:

1. Kill Decision Fatigue with the Lean ADR Log

Decisions shouldn’t all take the same amount of time. Fueled by Jeff Bezos’ famous framework of Type 1 (One-Way Door) and Type 2 (Two-Way Door) decisions, our lean Architecture Decision Record (ADR) Log lets your team instantly categorize choices by their reversibility.

• Type 2 choices can be walked through quickly, allowing your developers to ship low-risk features instantly.
• Type 1 choices (critical, irreversible infrastructure shifts) are flagged for deliberate, precise architectural review.

2. Stop Arguing for “Refactoring Time”

Every tech lead has lost the battle of asking product managers for a generic “refactoring sprint.” Business partners don’t care about clean code; they care about business risk.

The Tech Debt Dashboard & Risk Registry provides a plug-and-play matrix that quantifies code liabilities into actionable, mathematical risk scores. By visualizing systemic risks clearly, you stop begging for maintenance windows and start getting voluntary sprint allocations to clear bottlenecks.

3. Speak the Language of the Boardroom

The pack includes our exclusive Executive Guide: “Translating Engineering Risk into Business Impact.” This is your definitive boardroom playbook. Use this to reframe engineering friction into the commercial realities—like revenue risk, compliance exposure, and opportunity cost—that get immediate buy-in from your CEO, CFO, and CRO.

Built for High-Velocity Teams

The Scaling Engineering Governance Pack isn’t a rigid, over-engineered system full of hidden databases or aesthetic bloat. It’s built cleanly for Notion, fully modular, and ready for immediate deployment. You can run the components as standalone trackers or seamlessly drop the linked database windows into your current workspace master pages.

Stop letting misaligned priorities slow down your ship cycles. Build a scalable foundation that keeps your velocity high and your operational risk low.

👉 Secure your copy of The Scaling Engineering Governance Pack on Gumroad today and clone the framework straight into your workspace.

Architect Forward and Transform.

At first it felt like Stack Overflow on steroids.

I needed an answer → AI gave me something plausible → copy, paste, run.

A lot of what people now call “vibe coding”.

Prompt something. Accept what comes back. Fix errors as they appear. Repeat until it works.

It’s messy, but it’s also an incredible way to learn quickly.

Early on I experimented with everything I could get my hands on.

Running models locally on my Mac through Ollama. Trying different open models. Testing dev workflows.

It was interesting technically, but the development experience wasn’t great and iteration was too slow. I eventually moved fully to cloud models.

Claude and ChatGPT became the main tools.

At that stage the workflow looked something like:

prompt → generate → paste → run → debug → repeat.

I was learning UI patterns, databases, application structure — while also learning how to prompt effectively.

Back then the Claude free-tier memory limits slowed things down at times, so I bounced between Claude and ChatGPT depending on what I needed.

Eventually I actually got something running.

And I was excited.

Then the scope widened. things starting coming together for me under ArchitectFWD™ as I thought about the opportunity.

I started using AI for things outside the code:

• voiceover scripts
• AI voice tools
• image generation for socials
• content drafts

At some point this all turned into two separate products.

• prfrm — first I tested and learnt here. I focused on performance management for individuals and teams. AI-assisted goal creation, alignment and progress visibility.

• Enterprise — a platform for strategy, architecture and organisational alignment. I am super excited at how this will change outcomes for organisations who choose to join me on this journey.

Two very different problems. Two very different ways of thinking. But they’re aligned - Strategy and Execution. Structure and organisation. people, assisted by AI.

Trying to juggle both in ad-hoc AI chats stopped working pretty quickly.

Around the same time my Google Workspace renewal rolled around and I started using Gemini more heavily. That shifted things again.

Less Claude. Less ChatGPT. No more local Ollama.

The workflow became much more structured.

I started introducing:

• Product requirements documents (PRDs)
• explicit VS Code rules settings
• better context engineering
• more deliberate prompts

Most of my work now happens inside the IDE, with AI acting more like an assistant than the driver.

Gemini and ChatGPT still help with quick domain questions, explanations, and research — but the development experience and flow is much tighter.

There have definitely been mistakes along the way.

• Lost code.
• Poor commit discipline.
• Letting AI refactor too much at once.
• Learning the hard way where guardrails matter.
• Tests and migrations breaking databases

But the practices are improving.

Is it fully spec-driven development?

Not yet.

But prompts are increasingly behaving like specifications.

I’m also starting to ask for tests. Do I run them?

Is it proper TDD? Probably not.

But let’s be honest — how many teams claiming TDD actually do it well?

I am experimenting now with something closer to spec-driven development. It’s not there yet.

• Write the intent.
• Set the rules.
• Let the AI implement.
• Test
• Commit
• Ship

Sometimes the responses still need steering.

But the speed difference is remarkable.

Issue a prompt. Tell the AI to follow the rules. Lock the screen. Come back later.

It’s a pretty interesting way to build. 🚀

This is architecture, moving forward.

Architect Forward and Transform.

ArchitectFWD™ was built to close that gap.

We believe architecture isn’t documentation.

It’s direction.

Architecture is how strategy becomes real — how intent becomes coordinated action, and complexity becomes momentum.

The forward motion in FWD™ isn’t decorative. It’s deliberate.

It represents progress over perfection. Clarity over noise. Movement over stagnation.

ArchitectFWD™ isn’t a single product. It’s a structured ecosystem of advisory and platforms designed to support leaders navigating growth, scale, and transformation.

Every part of ArchitectFWD™ answers one question:

What’s the next right move — and how do we execute it well?

This is architecture, moving forward.

Architect Forward and Transform.

The architectFWD™ ecosystem as we call it is maturing and we want the branding to reflect that.

ArchitectFWD™ provides trusted strategy, architecture, and advisory expertise, expressed through a family of purpose-built platforms.

ArchitectFWD™ Enterprise is the flagship platform of the ArchitectFWD ecosystem for strategy, architecture & alignment.

Access ArchitectFWD Enterprise Platform - Software as a Service Now

ArchitectFWD™ prfrm™ is all about team and organisational performance & execution.

check out prfrm™ - by ArchitectFWD - Software as a Service

Closing thoughts

Join me in welcoming this new phase of the architectFWD strategic, transformation and advisory function increasing its reach through the architectFWD ecosystem platforms ArchitectFWD Enterprise Platform and prfrm™ - by ArchitectFWD .

The issue

This error is a known, recurring bug within the Gemini Code Assist extension for VS Code, specifically affecting users on certain operating systems or hardware configurations, including some on macOS M1/M2 chips.

The traceback shows a Go language panic (panic: runtime error: invalid memory address or nil pointer dereference), which is an internal crash within the extension’s backend process (written in Go), often triggered during the code analysis/tokenization phase (tokenizeFunc).

Since version 2.57, similar issues have been widely reported. The most reliable solution is to downgrade the extension version.

The fix

Recommended Fix: Downgrade the Extension The version you are running, v2.59.0, appears to be affected by this instability. The best immediate fix is to roll back to a known stable version.

1. Open Extensions View: In VS Code, go to the Extensions tab (Cmd+Shift+X on Mac).

2. Find the Extension: Search for Gemini Code Assist.

3. Access Downgrade Menu: Click the gear icon (⚙️) next to the extension.

4. Select Downgrade: Choose “Install Another Version…”

5. Install Stable Version: Select a version prior to 2.57.0, such as 2.56.0 or 2.55.0. These older versions are frequently cited by users as stable.

6. Disable Auto-Update: To prevent VS Code from immediately updating it again, click the gear icon (⚙️) again and select “Disable Auto Update” for the extension.

7. Restart VS Code: Completely close and reopen VS Code to ensure the downgraded version loads correctly.

Closing thoughts

I performed the downgrade and its been around 5 minutes, looks like it fixed it. Let’s wait for that new version. Right, back to getting some things done.

Zero-Downtime or Zero-Risk? Your EC2 Update Strategy

I run my services using a mix of AWS managed services and also EC2. For EC2, breaking a running stack to apply a patch is a massive failure. So, here are the two strategies to handle EC2 updates.

Option 1: The Zero-Risk Strategy (Migration)

This is the gold standard for any major OS version change, and the safest strategy for any update if your uptime requirements are near 100%. The premise is simple: We build a perfect new server, test it, and then swap the traffic.

1. Prep & Backup

Before you touch anything on the old server, create a complete recovery point.

• Create an AMI: In the EC2 Console, select your instance → Actions → Image and templates → Create Image. This is your instant, guaranteed rollback.
• Backup Data: Use scp or aws s3 sync to copy your application, data and config files to a separate location.

2. Build & Configure The New Instance

Launch a new EC2 instance using the latest Amazon Linux 2023 AMI.

• Match Settings: Use the same Instance Type, VPC, and Security Group as the old server.
• Install Packages: SSH into the new instance and install your stack:

  sudo dnf update -y
  sudo dnf install nginx certbot python3-certbot-nginx -y # and your specific packages
  

• Configure & Migrate: Copy your Nginx configuration files, Certbot files, and application code/data from the old server to the new one. Ensure file permissions are correct.

3. Testing

This step ensures the new server is flawless before the public sees it.

• Local Host File Trick: Temporarily edit your local machine’s hosts file to point your domain names to the new instance’s Public IP. Or set up new certs in ACM / certbot and routes in AWS Route 53 if preferred.
• Test Everything: Browse both your sites. Check all features, forms, and database interactions. Once satisfied, remove the entries from your hosts file.

4. Cutover (The Switch)

When you are 100% confident, update your DNS records to point the domain names to the new instance’s Public IP (or Elastic IP). Wait for the DNS TTL to expire. Traffic is now safely serving from the updated server.

You could likely make another AMI image at this point or during the process so you have it as a recovery point.

Option 2: The High-Speed Strategy (In-Place Upgrade)

If your upgrade is a minor version bump within the same OS (like AL2023.6 to AL2023.9), an in-place upgrade is faster. This is how I handle routine patching, but you must follow the safety protocol.

1. First Step (Mandatory)

Just like the migration, your AMI backup is non-negotiable.

Action: Create an AMI (Amazon Machine Image) now. Do not skip this.

2. 🔎 Risk Assessment: What Could Break

Since Nginx relies on OpenSSL and the kernel, these are your potential failure points. Breaking changes are rare in minor AL2023 updates, but they do happen via dependency bumps.

Now we update.

3. The Targeted Update

AL2023 uses versioned repositories. We need to specifically target the latest version (e.g., 2023.9.20251117) to pull all patches.

SSH in and run these commands sequentially:

# 1. Preview the changes (see which packages will be touched)
sudo dnf check-update --releasever=2023.9.20251117

# 2. Execute the upgrade command
sudo dnf upgrade --releasever=2023.9.20251117 -y

4. Final Checks And Verification

The new packages are installed, but the old kernel and services may still be running.

• Verify Nginx Config: Run this immediately after the upgrade:

  sudo nginx -t
  

• Reboot: If the kernel was updated, you must reboot.

  sudo reboot
  

• Final Check: Once back up, ensure Nginx is running and your sites are online:

  sudo systemctl status nginx
  

Closing thoughts

For major OS version changes (e.g., AL2 to AL2023), Migrate.

For minor patches within AL2023, the In-Place Upgrade is quick and efficient—as long as you have that fresh AMI backup.

Stripe

Stripe is integrated into my apps for payments and subscription plans. I also use a concept of AI credits for my apps and so those need to be refreshed for each active subscription period.

I was adding some new functionality to ArchitectFWD Enterprise (check out ArchitectFWD Enterprise Platform - Software as a Service) and so to test the AI credits and Stripe subscriptions, I started up the stripe cli listener from the command line.

FATAL Error while authenticating with Stripe: Authorization failed, status=401, body={ “error”: { “code”: “api_key_expired”, “doc_url”: “https://stripe.com/docs/error-codes/api-key-expired”, “message”: “Expired API Key provided: rk_test_*********************************….”, “type”: “invalid_request_error” } }

The fix

Log back into the Stripe dashboard and enable test mode. I’ve not yet set up the new sandbox functionality but test mode still works so I continued to set the new API keys in test mode.

Go to API Keys in the Stripe dashboard and under the standard API Keys, rotate the keys Publishable Key and Secret Key.

Then also refresh the webhook key on the Stripe developer console in the dashboard.

Go back to the command line and type

stripe config –set test_mode_pub_key pk_test_XXXXXXXX

Then the other key

stripe config –set test_mode_api_key sk_test_XXXXXXXX

These keys you should have from having performed the key rotations.

Then try start up the CLI again

stripe listen –forward-to http://localhost:8000/stripe/webhook

You should see this

Ready! You are using Stripe API Version [2024-06-20]. Your webhook signing secret is XXXXX

Set your webhook signing secret in your app and give it a test. I just created a new subscription in test mode in the Stripe dashboard.

Start up the Stripe cli -

2025-10-23 21:11:32 –> setup_intent.created [evt

looking at my logs for testing I can see

local.INFO: [StripeWebHookListener] Stripe Event setup_intent.created Payload: {“id”:”evt_…”

Looking good.

Closing thoughts

The test keys seem to have a maximum expiry length of 7 days, so get to testing and ship that feature!

AWS Bedrock

I am using AWS Bedrock and the API to embed AI in two apps I’m building currently.

When calling the API earlier I was given this error:

Error: Error executing “InvokeModel” on “https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-v2/invoke”; AWS HTTP error: Client error: POST https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-v2/invoke resulted in a 404 Not Found response: {“message”:”This model version has reached the end of its life. Please refer to the AWS documentation for more details.” (truncated…) ResourceNotFoundException (client): This model version has reached the end of its life. Please refer to the AWS documentation for more details.

Model Lifecycles

The message “This model version has reached the end of its life” indicates that the specific version of Anthropic’s Claude 2 model, identified as anthropic.claude-v2, is no longer supported or available for use on Amazon Bedrock.

This means that any applications or integrations relying on this particular model version will need to be updated to use a newer, supported Claude model. Anthropic and AWS typically provide information on model deprecations and recommended replacements.

I didnt get any notice perhaps its in the console.

Users are advised to migrate their usage to a suitable replacement model before the retirement date, as requests to deprecated models will fail after that point. For example, users who were utilizing anthropic.claude-v2 would need to migrate to a newer version like Claude 3 or Claude 4 models (e.g., Claude Sonnet 4, Claude Opus 4.1) which are available on Amazon Bedrock. Thorough testing of applications with the new models is recommended before the full transition.

Read the Bedrock model lifecycle page. It says “Amazon Bedrock is continuously working to bring the latest versions of foundation models that have better capabilities, accuracy, and safety. As we launch new model versions, you can test them with the Amazon Bedrock console or API, and migrate your applications to benefit from the latest model versions.

A model offered on Amazon Bedrock can be in one of these states: Active, Legacy, or End-of-Life (EOL)”

That link proceeds to give a information and list of active versions, legacy versions and end-of-life versions.

For legacy versions the page says “We will notify you when a model provider moves a model to the Legacy state. A model will be in the Legacy state for at least 6 months before the EOL date. While you can continue to use a Legacy model during this period, you should plan to transition to an Active model before the EOL date. New customers can’t use Legacy models and existing customers may lose access to Legacy models due to inactivity.”

For EOL models “EOL — After the EOL date, a model will be marked EOL in the console and in the following table. On, or soon after the EOL date, the model is no longer available for use in all AWS Regions and requests made to this version will fail, unless there is a private arrangement between you and the provider for continued access. You will need to migrate to the latest model by updating your application code before the EOL date. Migration will not happen automatically.”

The EOL page suggests I move to Claude Sonnet 4. I’ll do so in coming days.

Closing thoughts

As part of your governance practices you will need to be monitoring model lifecycle.

I’ve got a gap in this control and now have some migration and testing to do. I also need to figure out where the notifications on model lifecycle changes can be viewed and more reasonably subscribed to.