DEV Community: Shubham

handoff: Give the Next AI Agent the Context It Actually Needs

Shubham — Sun, 06 Sep 2026 01:14:21 +0000

AI-assisted engineering does not usually fail because an agent forgets everything. It fails because a new session receives the wrong kind of context. Give it too little and it repeats discovery, reopens decisions, or changes the wrong files. Give it an entire transcript and it has to untangle settled facts, abandoned branches, tool noise, and current work.

handoff is a skill for the seam between sessions. Invoked with /handoff, it compacts the active conversation into a handoff document that a fresh agent can read to continue the work. Its design is intentionally selective: it carries the live thread, references durable artifacts instead of copying them, saves the document to the operating system’s temporary directory rather than the workspace, includes suggested skills, and redacts sensitive material.

The central idea is compaction. Preserve momentum, not every word.

Why session changes are a real engineering boundary

A context switch happens more often than teams admit. A long thread approaches a limit. Someone stops work for the day. A specialist agent completes research and another agent implements. A human changes the task’s priority. A review uncovers a concern that needs a new conversation.

Without an explicit handoff, the next participant must reconstruct intent from code and chat history. Code tells you what exists, not always why it was chosen. A ticket may state the desired outcome but not the current blocker. A plan may be accurate but not reveal which task was half-finished when the session ended. The handoff fills that narrow but valuable gap.

What belongs in a high-quality handoff

The live thread

State what is in flight in plain language. “Implementing organization invitations” is too broad. “Persistence and service-layer authorization are complete; email delivery remains unimplemented because the existing notification abstraction does not support signed links” is useful.

Why it matters now

Explain the immediate context: a test is failing, an API decision is pending, a migration must be reviewed, or a release is blocked. This helps the next agent choose the right first action rather than simply continuing the last visible edit.

Settled decisions

List only decisions the next session must not accidentally undo. Include the rationale briefly and point to the specification, ADR, issue, or code path that is authoritative. For example: “Invites expire after seven days; accepted in ADR-014. Do not change token model without product approval.”

Open questions and blockers

Be concrete about what is unresolved, who owns the choice, and what evidence is needed. “Need to decide email provider” is weak. “Choose whether to send through the existing asynchronous notification service or add a transactional provider; inspect incident history and delivery requirements first” gives the next agent a route forward.

References, not duplicates

handoff specifically avoids restating material already captured in a spec, plan, ADR, issue, commit, or diff. It references a path or URL instead. That is a safeguard against documentation drift. If a spec changes, the project has one source of truth rather than five copied versions in old handoff notes.

Why temporary storage matters

The skill saves handoff documents to the OS temporary directory, not the repository workspace. This is a useful design decision. A handoff is session glue, not necessarily a product artifact that should be committed, maintained, and discovered by every future developer.

That does not mean a handoff is disposable in the everyday sense. It may contain crucial information for the next session. It means it should not become another competing project document. Durable decisions belong in durable artifacts; the handoff points to them.

How to invoke it well

handoff is user-invoked rather than automatic. That is good: humans know when a transition is intentional. Pass a note describing what the next session is for so the document can be tailored to the continuation.

/handoff Next session will implement the API routes and integration tests for invitation acceptance. Preserve the settled authorization rules, current migration state, failing test details, and links to the approved spec and diff.

A targeted instruction leads to a targeted note. “Summarize everything” tends to reproduce the problem handoff is designed to solve.

A usable handoff template

Objective
- What outcome are we delivering?

Current state
- What is complete? What is partially complete?

Settled decisions
- Decision, rationale, authoritative reference.

Open questions / blockers
- What is unresolved, who owns it, what evidence is needed?

Validation
- Commands run, test results, environment assumptions.

References
- Specs, plans, ADRs, issues, commits, diffs, relevant files.

Next action
- The first concrete thing the next agent should do.

Suggested skills
- Which skill or workflow should be used next?

The template is deliberately operational. It gives a successor enough to act without pretending to be a full project history.

Example: weak versus strong

Weak: “Worked on auth. Some tests pass. Continue tomorrow.”

Strong: “Goal: add passwordless sign-in for existing users. Completed token persistence and expiry tests; API endpoint exists but is not wired to mail delivery. Decision: do not reveal whether an email belongs to an account see security section in docs/auth-spec.md. Blocker: current notification adapter cannot send template variables. Next: inspect adapter contract and propose the smallest compatible extension. Ran bun test auth: 18 pass, 2 skipped. Suggested skills: domain-model if adapter change affects notification domain; TDD for implementation.”

The strong version contains less total history but far more usable context.

Security and privacy

handoff is designed to redact secrets, passwords, API keys, and personally identifiable information. Do not treat automatic redaction as permission to paste secrets into a conversation. The safer practice is to reference secret-management locations and use neutral identifiers: “Production API credential is configured in the deployment secret store,” not the credential itself.

Also consider sensitive business context. A handoff can reveal incident details, customer behavior, or internal strategy. Keep it scoped to the recipient and store durable security findings in the appropriate controlled artifact.

Common mistakes

Turning the handoff into a transcript

Long chronological summaries force the next agent to reread history. Prefer current state, decisions, references, and next actions.

Failing to name the next action

A handoff that says “continue implementation” leaves the successor to choose a starting point. State the first file to inspect, command to run, or decision to obtain.

Duplicating the spec

Copying a plan makes it stale. Reference the canonical version and record only what changed in the live conversation.

Hiding uncertainty

Say when a conclusion is tentative. A false sense of certainty is more damaging than an explicit unresolved question.

Where handoff fits in an agent workflow

Use a planning skill to clarify a feature, a structured build workflow to implement it, concise execution mode when appropriate, and handoff at the transition point. Handoff is not a replacement for specs or commits. It is the bridge that makes those artifacts usable in the next context.

Bottom line

A good handoff lets a new agent inherit the work’s momentum without inheriting its noise. Capture the live thread, link the stable artifacts, make uncertainty visible, and state the next action. That is enough context to continue well and not so much that the next session starts by getting lost.

Sources

Caveman Ultra Mode: Make Your Coding Agent Say Less, Not Think Less

Shubham — Sun, 30 Aug 2026 09:17:59 +0000

AI coding agents have a communication problem. They can be technically capable and still make a development loop feel slow because every small action arrives with a paragraph of ceremony: a restatement of the ticket, a promise to investigate, an explanation of an obvious command, and a summary that repeats the first three things.

That style is sometimes useful. It is not useful all the time. When you are deep in a known codebase and want to diagnose a failing test, inspect a diff, or make a narrow fix, the value is usually in four things: what the agent found, what it changed, how it verified the change, and what remains uncertain.

Caveman is a skill/plugin built around that distinction. It makes a coding agent communicate in short, direct language its deliberately rough “caveman-speak” while aiming to leave code, commands, and errors byte-for-byte intact. The project describes this as making the agent’s mouth smaller rather than its brain smaller.

Ultra Mode is an interface choice

The useful way to understand Caveman is not as a substitute for reasoning. It is an interface choice for the execution phase of work. A terse agent should still inspect the repository, follow the test suite, notice ambiguity, and say when evidence is missing. It simply should not pad a simple finding with social filler.

Compare these two reports:

“I’ve taken a look at the component and the reason it is re-rendering is likely because a new object reference is created during each render cycle. I recommend using useMemo to memoize that object.”

“New object ref each render. Inline prop = new ref = re-render. Wrap in useMemo.”

The second version is not appropriate for a design document. For a developer actively debugging a React component, however, it is easier to scan and easier to act on. The underlying technical claim is the same.

What Caveman actually promises

The Caveman repository says it works with Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, and other agent environments. It claims “65% fewer output tokens” and emphasizes that the saving applies to output, not input context. Treat that figure as the project’s own claim, not as an independent benchmark or a guarantee for every model and task.

That caveat matters. Token savings vary with the agent, the task, the amount of tool output, and the prompt. Still, the basic mechanism is sound: if an agent stops producing repetitive prose, it emits fewer tokens and consumes less attention.

Where concise mode earns its place

Known-scope debugging

Suppose CI says an authentication test has failed. You want the agent to locate the relevant middleware, compare the expiry condition with the test, fix the defect, and report the result. You do not need a tutorial on authentication on every turn.

A useful compact report is: “Expiry check uses <=; test expects boundary valid. Changed to <. Target tests pass. Risk: confirm API contract for exact expiry instant.” It retains the evidence and the unresolved risk.

Small implementation loops

During a tightly defined change, concise updates keep the human in the loop. Ask for a plan once, approve it, then request short progress reports. The agent can say which files changed, which tests ran, and whether it needs a decision. This is especially useful when you are reviewing diffs alongside the agent rather than delegating an entire feature.

Terminal-heavy work

Commands, build output, migration results, and test failures already contain a lot of text. Adding a long prose explanation around every command makes the signal harder to find. Caveman’s stated rule of leaving commands and errors unchanged is important here: compress the commentary, not the evidence.

Code review follow-ups

After a review comment, the desired loop is often mechanical: inspect, decide whether the comment is valid, make a focused change, run validation. Terse reports help reviewers see the outcome without re-reading an essay.

Where Ultra Mode is a bad fit

Concise output can conceal uncertainty. Do not enable it blindly for the parts of engineering where nuance is the work.

Discovery and requirements: assumptions need to be stated, not compressed away.
Architecture: alternatives, constraints, and trade-offs deserve explicit comparison.
Security and privacy: threat models and residual risk require careful language.
Incident response: timelines, impact, and confidence levels must be precise.
Onboarding and teaching: the explanation is part of the deliverable.

The failure mode is not that short answers are inherently shallow. The failure mode is mistaking a short answer for a complete decision record.

How to preserve accountability

Use a compact reporting contract. For example:

Work in concise mode.
Before edits: inspect relevant files and state the likely cause in 1–3 bullets.
After edits: list files changed, validation run, result, and remaining risk.
Ask before making an irreversible or scope-expanding decision.

This gives the agent permission to be brief while defining the minimum evidence you expect. “Concise” should never mean “silent about a failed test” or “quiet about an assumption.”

A practical operating model

Split agent work into two modes. In decision mode, ask the agent to explore, explain, compare options, and surface uncertainty. In execution mode, once the approach is approved, use Caveman-style reporting to keep the loop fast.

Frame the task and constraints in normal language.
Ask for a short plan and acceptance checks.
Approve or revise the approach.
Switch to Ultra Mode for implementation.
Require exact tests, commands, and a final risk note.
Return to normal mode for a postmortem or architectural follow-up.

This avoids the false choice between a verbose agent and a reckless one. You can have a careful process and a compact execution interface.

Installation and activation

The project documents broad agent support and provides install instructions for macOS, Linux, WSL, Git Bash, and Windows PowerShell. Its README says Caveman can be turned on with /caveman or a request such as “talk like caveman,” and turned off with “normal mode.” Always use the repository’s current instructions for your particular agent harness; plugin conventions change quickly.

Common mistakes

Using it before the problem is framed

If your request is “make our billing system better,” terse mode will not make the request less ambiguous. First establish scope, owners, constraints, and measures of success.

Measuring only token count

A lower token count is useful only if it does not create more clarification rounds, missed constraints, or review burden. Measure cycle time and defect rate, not just output length.

Suppressing useful warnings

Tell the agent that blockers and risks must remain explicit. A one-line warning is better than no warning; a short report is not permission to omit it.

Bottom line

Caveman Ultra Mode is most valuable when verbosity is the bottleneck and the work is already understood. It can reduce output overhead and make development status easier to scan. It cannot replace design, testing, or engineering judgment. Use it to make execution quieter not to make important thinking disappear.

Sources

Caveman repository and README

Superpowers for Coding Agents: Turn Vague Requests Into Tested Changes

Shubham — Sun, 23 Aug 2026 11:55:36 +0000

The fastest way for an AI coding agent to create expensive work is to start coding too soon. A request arrives, the agent infers the missing requirements, selects an architecture, edits several files, and produces a plausible patch. The patch may compile. It may even pass a narrow test. But it can still solve the wrong problem.

Superpowers is a methodology and a set of composable skills intended to change that default. Rather than treating code generation as the first step, it asks the agent to clarify the outcome, develop and get approval for a design, make an implementation plan, use true red/green test-driven development, carry out the work in small tasks, and review what was built.

That is not bureaucracy for its own sake. It is a response to the fact that AI agents are very good at filling gaps with plausible assumptions.

The core idea: gates before generation

Superpowers describes a coding-agent workflow that begins when the agent recognizes it is building something. Instead of jumping into implementation, it steps back and asks what the user is really trying to accomplish. It then develops a specification, presents the design in readable chunks, and waits for sign-off before producing a detailed plan.

Only after approval does the workflow move to implementation. The repository emphasizes red/green TDD, YAGNI build only what is needed and DRY, avoiding needless duplication. It also describes subagent-driven development for executing and reviewing tasks.

Each gate exists because a different kind of failure is cheaper to catch early:

Clarification catches misunderstood outcomes.
Design review catches wrong shapes and missing constraints.
Planning catches hidden dependencies and sequencing errors.
Tests catch behavioral regressions.
Review catches mismatches between the intended change and the actual diff.

Why vague requests are dangerous

Consider the request: “Add team invitations.” That sounds actionable, but it leaves a large number of product and system decisions unanswered. Are invites email-based? Does an invitation expire? Can it be revoked? What role does an invited person receive? What happens if they already have an account? What happens if they belong to another organization? Is the action auditable? Can an administrator resend an invitation? Which failure states are visible to users?

A coding agent that immediately creates an invitations table has already made decisions. A structured workflow makes those decisions visible before they become database migrations, endpoints, and UI states that are expensive to unwind.

Phase one: establish the outcome

Good clarification focuses on observable success, constraints, and non-goals. Ask for the user story, affected actors, existing behavior that must remain stable, and the acceptance checks that will show the task is complete.

For the invitation example, a useful outcome might be: “Organization owners can invite an email address to a workspace. Invites expire after seven days, can be revoked, grant a selected role on acceptance, and must not expose workspace existence to unauthenticated users.” That is already more useful than “add invitations” because it gives design and tests a target.

Phase two: agree on a design

The Superpowers README describes showing design material in chunks small enough for a human to read and approve. That is a practical design principle for agent collaboration. A giant wall of architecture text is difficult to review; a sequence of focused decisions is easier to challenge.

A design should cover the parts most likely to create irreversible work:

Domain entities and ownership boundaries
API contracts and error behavior
Authorization checks
State transitions and lifecycle rules
Data migration and backward compatibility
Observability and operational failure modes
Explicit non-goals

Approval is not a ceremony. It is the moment a human says, “Yes, this is the product behavior we mean to own.”

Phase three: write an implementable plan

After design sign-off, the plan should break work into small, ordered tasks. Each task should identify the relevant files or components, the change, and the validation method. The plan should be specific enough that another competent developer or another agent can execute it without reinterpreting the original request.

For example, an invitation feature might be sliced into: define domain rules and tests; add persistence and migration; add service-layer authorization; expose API routes; implement email delivery abstraction; add UI states; add integration tests; document rollout and monitoring. The exact order depends on the codebase, but the principle is stable: build vertical, verifiable increments.

True red/green TDD with an agent

Superpowers emphasizes true red/green TDD. The important distinction is temporal: tests should express expected behavior before implementation is accepted. Writing tests after code can still be useful, but it often records what the implementation happened to do instead of what the system should do.

For an invitation flow, a red test might assert that a revoked invite cannot be accepted, that an expired invite produces a specific error, or that a non-owner cannot create an invite. The implementation then moves the tests to green. This makes behavior reviewable in a form more durable than conversational claims.

TDD does not guarantee a correct product decision. It guarantees that selected behavior is checked. That is why clarification and design must precede it.

Subagents and review

The methodology describes subagent-driven development: agents can work through specific tasks, inspect work, and review outcomes. Parallelism is useful only when task boundaries are real. Separate agents may investigate independent modules or review a completed change, but two agents editing the same design decision without coordination can multiply confusion.

Use subagents to create independent evidence: one investigates existing conventions, one drafts tests, one reviews a diff against the approved design. Keep a single source of truth for decisions and require the final reviewer to compare the result against that source.

When to use Superpowers

This approach is valuable for new features, multi-file refactors, regressions with unclear causes, public API changes, and tasks where a mistaken assumption creates real rework. It is deliberately not the fastest method for changing a typo, renaming a local variable, or making a clearly scoped configuration edit.

The question is not “Is this task large?” Ask instead: “What does it cost if the agent chooses the wrong interpretation?” If the answer is high, the structure pays for itself.

Adopting the workflow without overdoing it

Start with one medium-risk feature.
Require a written success statement and non-goals.
Review the design before code changes begin.
Require a task plan with tests attached to each behavioral slice.
Review the final diff against the approved design, not only against the tests.
Record what produced rework and tune the workflow.

Teams should not judge the method by how polished the agent’s plan sounds. Judge it by concrete outcomes: fewer late requirement changes, clearer diffs, more reliable tests, and less rediscovery during review.

What Superpowers does not replace

No agent workflow can replace product ownership, security review, or accountability for production changes. A well-structured plan can still optimize the wrong metric. A green suite can still omit a real-world edge case. Treat the framework as a way to make decisions and evidence visible not as a guarantee of correctness.

Bottom line

Superpowers is useful because it gives an eager coding agent permission to pause. It turns a vague request into an agreed design, a plan, tested behavior, and a reviewable change. For meaningful engineering work, that pause is often the fastest part of the process.

Source

obra/superpowers README

Use grill-me to Pressure-Test an AI Implementation Plan Before Code

Shubham — Sat, 15 Aug 2026 23:45:03 +0000

Many software mistakes begin as decisions that nobody explicitly made. A feature request sounds clear enough, an AI coding agent begins implementation, and the details get settled by whichever model output appears first. Later, the team discovers that “add roles,” “cache this endpoint,” or “support collaboration” contained several linked product, data, security, and rollout choices.

grill-me is designed for the moment before that happens. It is a manually invoked skill that interviews you about a plan or design until the important decision tree is resolved. It asks one question at a time, supplies a recommended answer, and waits for feedback before continuing. Crucially, if an answer can be discovered by inspecting the codebase, the agent should investigate rather than ask you to recreate repository facts from memory.

The name is playful. The underlying practice is serious: force a proposal to survive questions before code makes it expensive to change.

What grill-me is and is not

grill-me is not a general implementation workflow. It does not replace a specification, an issue breakdown, tests, or code review. It is a pressure-test for a direction that is not yet sufficiently settled to build.

That narrowness is its strength. Teams often need an agent to push back, not agree. A conventional assistant can be biased toward accepting the first plausible framing. A grilling workflow instead asks what would make the plan fail: what is ambiguous, what constraint is missing, what decision is being deferred accidentally, and what evidence should be checked in the repository.

Why one question at a time matters

A long questionnaire feels efficient but usually is not. It asks about details before the premise is fixed, and the answers become inconsistent. A sequential interview allows dependencies to resolve in order.

For example, consider “add organization-level roles.” The first question might be whether roles are global or scoped to each organization. That answer determines whether membership is a separate domain entity. The next question may be whether permissions are static role bundles or configurable. Only then does it make sense to ask about API shape, migration, administration UI, or audit requirements.

By proceeding one decision at a time, the skill turns a vague feature into a chain of explicit commitments.

Start with a proposal, not a blank page

The best grilling sessions begin with enough context to challenge. State the desired outcome, the affected users, known constraints, existing artifacts, and the decision you want help making. Do not ask “what should we build?” when you really mean “which of two approaches fits this codebase?”

Grill this proposal before implementation.
Goal: organization owners can invite members by email.
Constraints: existing RBAC model, no public workspace enumeration,
and invitations must be revocable.
Inspect the relevant auth and membership code first.
Ask one question at a time. Recommend an answer, explain the trade-off,
and record settled decisions and open risks.

This gives the agent a job: interrogate the plan using evidence, not invent the product from scratch.

Questions worth asking before code

Outcome and scope

What user behavior changes? Who can trigger it? Who can observe it? What explicitly remains out of scope? Scope questions prevent a small feature from quietly becoming a platform redesign.

Domain model

What entities exist? Who owns them? What states can they occupy? What transitions are allowed? For invitations: pending, accepted, revoked, expired, perhaps resent. Decide whether resending creates a new token, extends expiry, or simply reuses a record. These are product rules with storage consequences.

Authorization

Who may create, view, revoke, accept, or resend the resource? Are permissions checked at an organization boundary, a project boundary, or both? What information should a denial reveal? Authorization is not a final middleware detail; it belongs in the plan.

Failure and recovery

What happens when an email is already associated with a member? When delivery fails? When two administrators act simultaneously? When a client retries? A plan that only describes the happy path is still incomplete.

Compatibility and rollout

Will the change alter stored data, public APIs, permissions, or client assumptions? How will it be migrated? How will you monitor behavior after release? The right answer may be “no special rollout needed,” but it should be consciously chosen.

Use repository evidence

One of grill-me’s best rules is that codebase facts should be discovered, not delegated to the user’s memory. Before asking whether an endpoint follows REST or RPC conventions, inspect existing endpoints. Before proposing a new role table, inspect the existing authorization system. Before recommending a migration, inspect database conventions and deployment tooling.

This does not mean the codebase gets the final word. Existing patterns can be wrong or outdated. It means the agent should distinguish “we should deviate deliberately” from “we did not know the convention existed.”

What a successful session produces

The output should be more than a transcript. It should leave behind a concise decision record:

The confirmed outcome and non-goals
Key decisions and their rationale
Alternatives considered and rejected
Assumptions that need validation
Open risks or owners
The recommended next artifact: domain model, PRD, spec, issues, or implementation plan

This gives a later agent something durable to follow. It also makes review better because reviewers can see what the code is intended to embody.

Where grill-me fits now

AI Hero notes an important update from Matt Pocock: for coding-oriented planning, he now generally recommends domain-model as the starting point when you want to align a plan with codebase language, CONTEXT.md, and architecture decision records. The suggested broader sequence is domain-model → to-prd → to-issues → tdd.

This does not make grill-me obsolete. It gives it a clearer role. Use grill-me as a lighter, targeted pressure-test when you have a plan that needs interrogation. Use a broader domain-model workflow when the task needs deep alignment with the application’s vocabulary and existing decisions.

Common failure modes

Asking hypothetical questions forever

Questions should converge toward a decision. If a scenario has little likelihood or impact, note it as a risk rather than letting it block every other choice.

Letting recommendations become decisions

The agent can recommend; the responsible human should approve. Record when a recommendation is accepted, changed, or deferred.

Skipping evidence gathering

A beautiful interview based on false assumptions is still waste. Require inspection of relevant code, documentation, and recent diffs first.

Calling it planning when no artifact remains

Capture the conclusions. Otherwise the next implementation session will reopen the same questions.

A repeatable ritual

Write a one-paragraph proposal.
Link relevant files, tickets, ADRs, and constraints.
Ask the agent to inspect before questioning.
Run one-question-at-a-time grilling.
Record decisions, non-goals, and unresolved risks.
Turn the result into the next formal artifact.
Only then begin implementation.

The time spent here is not delay. It is a way to move uncertainty from code into conversation, where it is cheaper to resolve.

Bottom line

Use grill-me when a feature direction feels plausible but has not earned implementation yet. It is particularly valuable when several decisions depend on each other and you want an agent to challenge you rather than cheerlead. Code should be the result of a decision, not the place where the decision first becomes visible.

Sources

Four AI Agent Skills That Make Coding Workflows Sharper

Shubham — Sat, 08 Aug 2026 23:55:15 +0000

AI coding agents are often discussed as though they are a single tool: ask for code, receive code. In practice, useful agent work has stages. You need different behavior when the request is unclear, when a design has to survive scrutiny, when implementation is underway, and when work must move into a new session.

Trying to solve all four stages with one large prompt usually produces a compromise. The agent may be verbose while you need execution, eager while you need questions, or unable to resume work because the important context is buried in chat history.

This article covers four skills that address those distinct problems: Caveman for concise execution communication, Superpowers for structured development, grill-me for pressure-testing a proposal, and handoff for transferring the live thread to a fresh agent or session.

They are complementary. The goal is not to add more ceremony to every edit. It is to apply the smallest useful constraint at the moment it prevents the most waste.

The four failure modes of AI-assisted development

1. The agent starts coding before the work is understood

A request such as “add organization roles” hides decisions about membership, permission scope, migrations, audit trails, errors, and rollout. An agent can produce a plausible patch before any of those choices are explicit.

2. The agent agrees instead of challenging

Helpful assistants tend to accept a framing. That is dangerous when the framing is a proposal rather than a settled requirement. You need an interview that exposes dependencies and asks what could fail.

3. The agent talks too much during routine work

Once a direction is approved, long explanations can become friction. During debugging, review follow-ups, and small implementation loops, the useful output is usually a finding, a change, validation, and a risk note.

4. Context is lost at a session boundary

A new agent with no context repeats discovery. A new agent with a full transcript has to find the current state among outdated ideas and tool logs. Neither is a reliable way to continue a task.

The four skills map directly to those problems.

grill-me: challenge the proposal before code

grill-me is a manually invoked skill that interviews you about a plan or design one question at a time. It provides a recommended answer and waits for feedback. It should inspect the codebase when a fact is available there instead of asking the user to reconstruct it.

Use it when an idea is plausible but not settled. Good examples include a new API contract, a permission model, a caching strategy, a workflow redesign, or a schema change. The point is not to ask endless hypothetical questions. The point is to resolve the decisions that implementation would otherwise make accidentally.

Start with a concrete proposal. State the goal, constraints, existing artifacts, and desired output. Ask the agent to inspect relevant files first, then grill the plan one decision at a time. Keep a record of the resulting decisions, non-goals, open risks, and the next artifact to create.

AI Hero notes that Matt Pocock now generally recommends a broader domain-model workflow when coding plans need to be aligned with a project’s vocabulary, context files, and architecture records. grill-me remains valuable as a focused pressure-test when you want sharp questions rather than a complete modeling process.

Superpowers: turn decisions into a controlled delivery process

Once the direction is clear, Superpowers supplies the broader development workflow. Its repository describes a process where an agent clarifies the actual outcome, develops a specification and design, gets approval, creates an implementation plan, emphasizes true red/green TDD, and proceeds through implementation and review. It also supports subagent-driven development for work that has real task boundaries.

Use Superpowers for work where the cost of an incorrect assumption is meaningful: new features, public API changes, complex bugs, behavioral refactors, migrations, or security-sensitive changes. It is deliberately heavier than the process you need for a one-line typo.

The key benefit is the presence of gates. Clarification catches the wrong outcome. Design approval catches a poor shape. A plan makes sequencing visible. Red/green tests make selected behavior executable. Review compares the delivered diff with the approved intent rather than merely checking whether the code looks reasonable.

For a team-invitation feature, the workflow could establish expiry and revocation rules, define authorization boundaries, choose the token lifecycle, plan storage and migration, write failure-case tests, implement in small slices, and review the result against the original product behavior. Each step reduces the chance that a polished patch is solving an unowned problem.

Caveman: keep execution communication compact

Caveman changes an agent’s output style toward concise, direct language. Its README frames the goal as shrinking the agent’s “mouth,” not its “brain,” and says code, commands, and errors remain exact. The project claims 65% fewer output tokens; treat that as a project claim rather than a universal benchmark.

Caveman belongs after the important decisions have been made. It is excellent for a known-scope bug, a test failure, a terminal-heavy task, or a review follow-up. Instead of several paragraphs of acknowledgement, ask for: root cause, files changed, validation run, result, and remaining risk.

Concise mode is not the right choice when nuance is itself part of the deliverable. Do not compress discovery, architecture, security analysis, incident communication, or onboarding into slogans. The rule is simple: reduce filler, never evidence.

A practical operating pattern is to work in normal detail until the design is approved, then switch to concise execution reports. Require the agent to remain explicit about blockers and assumptions. A short warning is useful; an omitted warning is not.

handoff: carry the live thread across a boundary

handoff creates a compact document that a fresh agent can use to resume work. It captures what is in flight, why it matters, what should happen next, and suggested skills for continuation. Crucially, it references existing specifications, plans, ADRs, issues, commits, and diffs rather than copying them. It is saved to the operating system’s temporary directory, not the workspace, and is intended to redact secrets and personally identifiable information.

Use it before ending work, near a context limit, when moving a task between agents, or when deliberately resetting a conversation. Pass a note about the next session’s purpose so the handoff is tailored to the next action.

A good handoff names the objective, completed work, settled decisions, blockers, validation, canonical references, and one precise next action. “Continue tomorrow” is not enough. “Service-layer authorization is complete; inspect the notification adapter before implementing email delivery; the approved spec is at this path; targeted tests pass” is actionable.

The integrated workflow

Frame the request. State desired outcome, constraints, and non-goals.
Use grill-me. Pressure-test linked decisions and inspect repository evidence.
Use Superpowers. Convert settled decisions into an approved design, plan, tests, implementation, and review.
Use Caveman during execution. Keep updates compact while preserving findings, commands, test results, and risks.
Use handoff at transitions. Preserve only the resumable thread and point to durable artifacts.

Not every task needs every stage. A trivial local change might use none of them. A medium feature may need Superpowers and Caveman. A risky design change may begin with grill-me and end with handoff. The value is in choosing the appropriate control, not in mechanically invoking every tool.

How to adopt the stack

Start small. Pick one feature with meaningful ambiguity. Ask the agent to inspect the relevant code and grill the proposal. Require a reviewable design and test plan. Once approved, switch to short execution reports. At the first planned context switch, create a handoff and ask a fresh agent to continue from it.

Measure outcomes that matter: how many assumptions were caught before code, whether reviewers can explain why a diff exists, how often agents repeat discovery after a switch, and whether concise reporting shortens the human review loop. Do not judge success only by token count or by how impressive a generated plan looks.

Limits and guardrails

These skills do not replace accountable engineering judgment. They cannot decide product strategy, guarantee secure systems, or prove that acceptance criteria reflect real user needs. They help make decisions, evidence, and transitions visible.

Use source control, reviews, tests, observability, and normal release controls. Keep secrets out of conversations and handoffs. Treat agent recommendations as inputs to a decision, not the decision itself.

Bottom line

Reliable AI-assisted development is not about making an agent behave the same way all the time. Ask it to question when the plan is uncertain, follow a disciplined workflow when the change is consequential, communicate briefly when execution is clear, and hand off cleanly when context changes. Caveman, Superpowers, grill-me, and handoff each make one part of that system sharper.

Sources

The Golden Rule of Payout Systems: Why "Pending" is Never a Failure

Shubham — Sun, 02 Aug 2026 01:06:48 +0000

A timeout means your application did not receive a final answer. It does not prove that a bank, payment gateway, or payment partner did not receive or process the payout request.

That distinction is the foundation of safe payout design. When a payout outcome is uncertain, the system should preserve it as pending until it receives reliable evidence that the payout completed or failed. Treating uncertainty as failure can make funds available for a second transfer while the first transfer is still moving through the payment rail.

The result is one of the most expensive errors in payments: a duplicate payout.

A payout is not a synchronous request

A simple architecture diagram suggests a clean sequence:

A user requests a payout.
Your application calls a payment API.
The partner returns success or failure.
Your database records the result.

That model is useful for a happy-path demo. It is incomplete for production money movement.

A payout can cross several systems before the recipient receives funds:

User
  |
  v
Your application
  |
  v
Payment partner
  |
  v
Banking or payment rail
  |
  v
Recipient bank
  |
  v
Recipient account

Each boundary introduces failure modes that your application cannot observe directly. A network connection may close after the payment partner has accepted the request. A gateway may return an error while its internal worker continues processing. A payment rail may accept an instruction but delay its final result.

From your application’s perspective, several different events can look exactly the same:

Request sent
  |
  +--> Partner never received it
  |
  +--> Partner received it but did not process it
  |
  +--> Partner accepted it and is still processing it
  |
  +--> Payout completed, but the response never reached you

A timeout tells you only one thing: the caller has no final response. It says nothing conclusive about whether money movement started.

That is why a payment API response is not always the final source of truth. The payment flow may continue after the HTTP request has ended.

The state that systems often miss

Many applications model a transaction with two terminal states:

success
failure

Payout systems need a third state:

unknown

In implementation, that state is often named pending, processing, submitted, or status_unknown. The label is less important than its behavior.

An uncertain payout must not behave like a failed payout.

It should not:

Restore funds for a new payout automatically.
Trigger a new payout attempt with a new external reference.
Be removed from operational records.
Be treated as resolved because an API call failed locally.

It should remain visible and traceable until the system can establish an outcome.

Consider a timeout after a payout submission:

Payout initiated
  |
  v
Request sent to partner
  |
  v
Network timeout
  |
  v
Outcome unknown

An unsafe implementation turns that timeout into a failure:

Timeout
  |
  v
Mark payout failed
  |
  v
Restore user balance
  |
  v
Allow a new payout

If the first request was accepted before the timeout, the user can now create a second payout using money that is already committed to the first one.

The application has created a duplicate-payment risk because it replaced uncertainty with an unsupported conclusion.

Why a false failure costs more than a delay

Every payout platform balances two risks.

The first risk is a delayed payout. The user sees a pending state for longer than expected. Support may need to answer questions. The payout may require reconciliation before it reaches a terminal state.

The second risk is a false failure. The original payout succeeds, but the platform decides it failed and makes the funds available again.

These risks are not equivalent.

Delayed resolution

When a payout remains pending:

The user may have to wait.
The funds may remain unavailable temporarily.
Support volume may increase.
Operations may need to review exceptions.

Those costs matter. They are usually contained and reversible.

False failure

When a completed payout is marked failed:

The recipient may receive money twice.
The ledger can show an incorrect available balance.
A refund or retry may create another transfer.
Finance teams may need manual investigation.
Recovering funds may depend on recipient cooperation.
Audit and reporting records become harder to explain.

A pending payout creates an operational problem. A false failure can create a financial loss.

This is why payout systems should prefer delayed certainty over an incorrect terminal state. The default should be conservative:

A payout is not failed until an authoritative source confirms final failure.

Build a state machine that preserves uncertainty

The rule must exist in code, not only in documentation. A clear state machine prevents workers, webhooks, API handlers, and support tools from applying conflicting decisions.

A basic model can look like this:

created
  |
  v
submitting
  |
  +--> pending
  |      |
  |      +--> completed
  |      |
  |      +--> failed
  |
  +--> failed

The important rule is that failed requires evidence.

created
  -> submitting
  -> pending
  -> completed

submitting + documented final rejection
  -> failed

submitting + timeout or connection reset
  -> pending

pending + confirmed completion
  -> completed

pending + confirmed final rejection
  -> failed

A timeout is not a final rejection. A connection reset is not a final rejection. An unrecognized response is not a final rejection.

Even an HTTP 5xx response should not automatically mean the payout failed unless the payment partner explicitly documents that response as proof the request was not accepted or processed.

Separate transport status from payout status

Transport signals describe communication between systems. Payment states describe the outcome of money movement. They should not be treated as the same thing.

Signal

What it proves

Safe payout state

Request accepted by partner

The partner accepted the submission

pending or processing

Documented terminal success

The partner reports a completed outcome

completed

Documented terminal rejection

The partner reports the payout cannot proceed

failed

Timeout or connection reset

Your application lacks a response

pending or status_unknown

Invalid or incomplete response

The response cannot establish outcome

pending or status_unknown

Persist the original payout intent before sending the external request. Keep the fields needed to resolve it later:

Internal payout ID
Idempotency key
Attempt ID
External reference, when available
Amount and currency
Recipient identifier or beneficiary reference
Submission time
Latest known external status
Raw partner response or error details, where appropriate

Do not overwrite earlier evidence when a later status check changes the payout state. An audit trail is essential when support or finance teams need to reconstruct what happened.

Retries need idempotency

Retries are necessary in distributed systems. They are also one of the main ways duplicate payouts occur.

The core rule is simple:

Retry an uncertain submission only when the receiving system can identify it as the same payout attempt.

That usually means sending a stable idempotency key.

Payout intent: payout_123
Attempt: attempt_001
Idempotency key: idem_abc

If the request times out, a transport retry should use the same idempotency key:

Retry submission
  |
  v
Idempotency key: idem_abc

The receiving system can then return the existing result or continue the original request instead of creating a second payout.

A new idempotency key changes the meaning of the request:

Retry submission
  |
  v
Idempotency key: idem_xyz

Depending on the partner’s behavior, that may be interpreted as a brand-new payout.

Transport retries and business retries are different

A transport retry attempts to deliver the same request again. It uses the same idempotency key and should refer to the same payout attempt.

A business retry happens after a confirmed terminal failure. It creates a new payout attempt because the old one is known not to have completed.

Payout intent: payout_123

Attempt 1
  idempotency key: idem_abc
  final status: failed

Attempt 2
  idempotency key: idem_def
  final status: pending

The payout intent connects both attempts. The attempt IDs and idempotency keys keep their external submissions distinct.

Before creating a new business retry, check whether the earlier attempt has a confirmed terminal status. If the old attempt is still unknown, resolve it through a status query or reconciliation process first.

if finalFailureConfirmed(attempt):
  createNewAttempt(payoutIntent)
else if outcomeUnknown(attempt):
  queryPartnerStatus(attempt)
  scheduleReconciliation(attempt)
else:
  continueNormalProcessing(attempt)

If a provider does not support idempotency, automatic retries after an unknown outcome are unsafe. Queue the payout for review or status resolution instead.

Reconciliation resolves what APIs cannot

A synchronous API response captures one point in time. Reconciliation compares your internal records with external payment records after the fact.

It closes the gap between:

What your application thinks happened.
What the payment partner reports.
What the banking or payment rail processed.

For payouts that remain pending, reconciliation should compare the details that identify a transaction:

Internal and external references
Amount and currency
Beneficiary details or recipient reference
Submission date and time
Latest known partner status
Settlement or completion records, where the rail provides them

The cadence should match the reporting and settlement behavior of the rail you operate. Some partners provide near-real-time status APIs. Others provide files or reports later. Your system should account for that delay rather than treating it as a failure.

Reconciliation is also an incident control

Reconciliation can reveal problems that request-response processing cannot:

A payout completed after a client timeout.
A payout marked completed without a matching external record.
Multiple external submissions for the same payout intent.
A pending payout that has exceeded its expected resolution time.
A mismatch between ledger entries and payment records.

Every mismatch should enter an exception queue with an owner, an audit note, and a next action. A queue without ownership is only a list of unresolved risk.

Operational rules and common mistakes

Rules that keep uncertainty safe

Keep funds unavailable for a second payout while the first outcome is unknown. The exact accounting treatment depends on the product, but the same balance must not support two active payout attempts.
Make state transitions idempotent. A repeated webhook, reconciliation record, or worker retry must not apply ledger changes twice.
Use webhooks as signals, not the only record. Webhooks can arrive late, repeat, or fail to arrive. Combine them with status queries and reconciliation.
Record every payout attempt. Do not delete ambiguous records. They hold the identifiers required to determine the outcome.
Alert on stale pending payouts. Define expected resolution windows by rail and route overdue cases to operations.
Give support useful context. Show the payout reference, current state, latest update, last status check, and planned next step.

Common mistakes

Refunding immediately after a timeout

A timeout can occur after the payment partner accepted the request. Restoring the balance immediately can make the funds available for another payout.

Use pending until a final result is confirmed.

Retrying with a new idempotency key

A new key may tell the partner to create another payout rather than resume or return the existing one.

Reuse the original key for a transport retry. Create a new key only for a confirmed new attempt.

Treating HTTP success as settlement

An accepted request is not always a completed payout. It may still be queued, screened, rejected later, or waiting on another system.

Model acceptance and completion as separate states when the payment rail requires it.

Treating a webhook as final proof without validation

A webhook should be authenticated, deduplicated, and checked against the payment partner’s documented status model. It may be delayed or repeated.

Removing ambiguous records to keep dashboards clean

An unresolved payout is not noise. It is a financial record that requires a final outcome. Keep it visible until reconciliation resolves it.

Key takeaways

A timeout means the caller lacks an answer. It does not prove a payout failed.
Model uncertainty as a durable pending, processing, or status_unknown state.
Move a payout to failed only with reliable evidence of a terminal rejection.
Use stable idempotency keys for transport retries.
Treat confirmed failures as new business attempts, with new attempt records.
Reconcile non-final payouts against the authoritative records available for the payment rail.
Prefer a temporary pending state over a duplicate transfer.

Conclusion

Payout systems must be designed for incomplete information. Networks fail, responses disappear, and external systems may continue processing after your request has timed out.

The safe response is not to guess.

When the payout outcome cannot be proven, preserve the state as pending, retain the identifiers needed to investigate it, and reconcile it until a final result is available. That choice may delay resolution, but it prevents the system from turning uncertainty into a duplicate payment.

Coming Next Week

Next week, I’ll share four AI agent skills I use to make my coding workflow faster, clearer, and easier to manage.

A practical look at the small systems behind better AI-assisted engineering.

Type-Driven Security: Reducing OWASP Risk With Strong Types

Shubham — Sun, 26 Jul 2026 01:07:06 +0000

TypeScript cannot sanitize HTML, prevent SQL injection, or authorize requests. Those controls must run at runtime.

It can reduce mistakes inside an application: returning database rows from an API, mixing tenant and user IDs, treating unvalidated JSON as trusted input, or passing vague permission booleans through several layers. The useful pattern is to model trust boundaries explicitly, then keep runtime checks close to the conversion point.

What TypeScript can and cannot do for security

A type system helps when a security property concerns the shape, origin, or permitted flow of values inside an application. It can distinguish a public API response from a database row. It can reject a ProjectId where a UserId is required. It can require a caller to provide a verified access capability before invoking a sensitive operation.

This moves some failures from production behavior to compiler feedback. A refactor that returns passwordHash can fail review because the endpoint must return a public DTO. A tenant-scoped repository method can reject arguments from the wrong domain before tests run.

TypeScript is erased at runtime. An attacker does not send a server a TenantId; they send JSON, headers, cookies, URLs, and request bodies. A cast such as value as TenantId is a developer assertion, not proof that the value is valid.

Keep the responsibility of each control clear:

Control

Problem it addresses

Static types

Accidental misuse of values in application code

Runtime schemas

Malformed or untrusted external data

Authentication and authorization

Whether a caller may perform an action

Parameterized SQL

SQL injection through query data

Output encoding and sanitization

Browser injection risks such as XSS

Tests, monitoring, and review

Regressions outside compiler coverage

Types are one layer. They work when they describe boundaries enforced elsewhere in the system.

Model boundaries instead of passing persistence objects around

A common source of accidental exposure is treating an ORM model or database row as the application’s universal user object. A handler loads a user and returns it. Another handler sends the same object to a logger. Later, a migration adds mfaSecret, passwordHash, a reset token, support notes, or billing metadata.

Every serialization site now needs to remember which fields to remove. This deny-list approach fails when the schema changes faster than callers are audited.

Separate representations based on where data may travel:

Persistence model: Matches stored data and may include sensitive fields.
Domain model: Represents business concepts and operations.
Request DTO: Represents data accepted by a specific endpoint.
Response DTO: Represents data intentionally exposed by an endpoint.
Log event: Contains fields approved for observability.

Not every entity needs each representation. The split has the most value for users, credentials, payments, tenancy, permissions, and objects with internal-only state.

This database row must never be emitted directly at an HTTP boundary:

type UserRow = {
  id: string;
  email: string;
  passwordHash: string;
  mfaSecret: string | null;
  internalNotes: string | null;
  passwordResetToken: string | null;
};

A response DTO states what the endpoint may reveal:

type PublicUserDto = {
  id: string;
  email: string;
};

function toPublicUser(user: UserRow): PublicUserDto {
  return {
    id: user.id,
    email: user.email,
  };
}

The important decision is the allow-list. Adding a column to UserRow does not add it to PublicUserDto. A new sensitive field remains private until someone intentionally exposes it.

async function getCurrentUser(req: Request, res: Response) {
  const user = await users.findById(req.auth.userId);

  if (!user) {
    return res.status(404).json({ error: "User not found" });
  }

  return res.json(toPublicUser(user));
}

The mapper is a review point. Requirements to add displayName or an avatar URL appear as a small, visible DTO change.

Apply the same rule to logs

Logging arbitrary objects is another data-exposure boundary. This code is easy to add while debugging and hard to audit later:

logger.info({ user, requestBody: req.body }, "login attempt");

It may record credentials, tokens, personal data, or columns added by a later migration. Prefer event-shaped logs:

type LoginAudit = {
  userId: string;
  outcome: "success" | "failure";
};

const event = {
  userId: user.id,
  outcome: "success",
} satisfies LoginAudit;

logger.info(event, "login attempt");

For failures, log a stable error code instead of the raw request body. If support workflows need selected input, create a redaction function and test that sensitive fields never appear.

type LoginFailureAudit = {
  emailDomain: string | null;
  reason: "invalid_credentials" | "account_locked";
};

function toLoginFailureAudit(
  email: string,
  reason: LoginFailureAudit["reason"],
): LoginFailureAudit {
  const [, domain] = email.split("@");

  return {
    emailDomain: domain ?? null,
    reason,
  };
}

Logger redaction settings and ORM serialization hooks are useful backup controls. The log call site should still show the intended data.

Use DTOs and allow-list serialization

Explicit DTOs prevent another problem: endpoint contracts changing because internal models change. ORM relations, joins, virtual fields, and serializer defaults can expose fields the endpoint author did not intend to publish.

Keep response mapping near the API layer. Repository methods should return information needed by the domain layer. Controllers or presentation modules should decide the public contract.

type ProjectRow = {
  id: string;
  tenantId: string;
  name: string;
  visibility: "private" | "team";
  archivedAt: Date | null;
  billingAccountId: string;
};

type ProjectDto = {
  id: string;
  name: string;
  visibility: "private" | "team";
};

function toProjectDto(project: ProjectRow): ProjectDto {
  return {
    id: project.id,
    name: project.name,
    visibility: project.visibility,
  };
}

This repetition records a policy decision. tenantId, archivedAt, and billingAccountId are not part of this API contract.

For larger APIs, use a presentation layer or serializer module. Avoid generic pick() helpers that scatter unreviewed field lists across the codebase. Named mappers are easier to search, test, and review.

Integration tests should verify real JSON responses, not only TypeScript assignments. Types cannot protect an endpoint that bypasses the mapper or an ORM plugin that serializes a model directly.

it("does not expose credential fields", async () => {
  const response = await request(app)
    .get("/v1/me")
    .set("authorization", userToken);

  expect(response.body).toEqual({
    id: expect.any(String),
    email: "person@example.com",
  });
  expect(response.body).not.toHaveProperty("passwordHash");
  expect(response.body).not.toHaveProperty("mfaSecret");
});

Make identifiers and authority explicit

A string does not state whether it identifies a tenant, user, project, invoice, or external provider account. Plain strings are easy to mix, especially in multi-tenant services where a missing tenant constraint can expose another customer’s data.

Branded types add nominal meaning to TypeScript’s structural type system:

declare const tenantBrand: unique symbol;
declare const userBrand: unique symbol;
declare const projectBrand: unique symbol;

type TenantId = string & { readonly [tenantBrand]: true };
type UserId = string & { readonly [userBrand]: true };
type ProjectId = string & { readonly [projectBrand]: true };

A repository signature can then state its scope:

async function loadUser(tenantId: TenantId, userId: UserId) {
  return db.query(
    "SELECT id, email FROM users WHERE tenant_id = $1 AND id = $2",
    [tenantId, userId],
  );
}

Calling loadUser(tenantId, projectId) is a type error. This does not prove the query is correct, but it prevents swapped-argument bugs that can look valid in review.

Construct brands only after validation

Do not export a generic conversion helper that converts any string into any brand. It defeats the purpose. Create domain values after validating data at a boundary.

function asTenantId(value: string): TenantId {
  if (!/^[0-9a-f-]{36}$/i.test(value)) {
    throw new Error("Invalid tenant ID");
  }

  return value as TenantId;
}

In production, prefer a UUID parser or the identifier format used by the system instead of maintaining a broad regular expression. One small module should own the cast and validate before casting.

Brands provide no runtime protection. Database constraints, query predicates, row-level security where appropriate, and authorization checks remain necessary.

Model verified authority as a capability

A boolean such as canEdit is easy to pass through several layers, disconnect from its resource, or accidentally derive from untrusted input. A capability type keeps the checked user and resource together.

Use a private brand so modules importing ProjectEditor cannot construct it with a normal object literal.

// project-access.ts
const projectEditorBrand: unique symbol = Symbol("projectEditor");

export type ProjectEditor = {
  readonly userId: UserId;
  readonly projectId: ProjectId;
  readonly [projectEditorBrand]: true;
};

export async function requireProjectEditor(
  userId: UserId,
  projectId: ProjectId,
): Promise<ProjectEditor> {
  const membership = await memberships.find(userId, projectId);

  if (!membership || membership.role !== "editor") {
    throw new ForbiddenError();
  }

  return {
    userId,
    projectId,
    [projectEditorBrand]: true,
  };
}

export async function renameProject(access: ProjectEditor, name: string) {
  return projects.rename(access.projectId, name);
}

The request handler first authenticates the caller, then loads trusted membership data, then obtains the capability:

const access = await requireProjectEditor(req.auth.userId, projectId);
await renameProject(access, input.name);

Keeping the brand private prevents importing modules from constructing this value with an object literal. It does not prevent unsafe casts. Authorization still depends on trusted runtime checks.

Every relevant request must verify identity, tenant membership, ownership, and current policy. A stale role cache, an incorrectly scoped lookup, or a cast can still create an authorization flaw.

Validate data before creating domain values

External values are unknown until checked. This includes more than HTTP request bodies:

URL parameters and query strings
Headers, cookies, and bearer-token claims
Environment variables
Webhook payloads
Queue messages and event streams
Imported CSV files
Third-party API responses
Database data when schemas or migrations are not fully trusted

TypeScript interfaces do not validate any of these values. A request annotated as CreateProjectInput still arrives as bytes over the network.

Use a runtime schema at the boundary, then infer the TypeScript type from that schema. This avoids maintaining two sources of truth.

import { z } from "zod";

const CreateProjectSchema = z.object({
  name: z.string().trim().min(1).max(120),
  visibility: z.enum(["private", "team"]),
}).strict();

type CreateProjectInput = z.infer<typeof CreateProjectSchema>;

function parseCreateProject(body: unknown): CreateProjectInput {
  return CreateProjectSchema.parse(body);
}

.strict() is a policy choice. Rejecting unknown keys can catch client bugs and prevent accidental acceptance of fields such as ownerId or role. Some public APIs intentionally ignore unknown fields for forward compatibility. Choose and document the behavior.

Schema validation checks shape and local constraints. It does not enforce business rules that depend on current state. A valid project name may already be in use. A valid projectId may belong to another tenant. A valid visibility value may be unavailable to the caller’s plan or role.

A safe request flow is usually:

Authenticate the request.
Parse and validate untrusted syntax and shape.
Convert validated primitives into domain values where needed.
Load current resource and membership state.
Authorize the requested operation.
Apply business rules and write through scoped data access.

Set resource limits separately. A schema that allows a 120-character string does not limit the HTTP request body. Configure body-size limits, upload limits, timeouts, queue payload limits, and rate limits at the relevant layers.

Keep SQL parameterized

Types can clarify repository inputs. They do not make string interpolation safe. SQL injection prevention depends on a database driver or query builder that sends data separately from SQL syntax.

Use parameter placeholders for values:

const result = await db.query(
  "SELECT id, email FROM users WHERE tenant_id = $1 AND id = $2",
  [tenantId, userId],
);

Do not interpolate values into query text, even if the values have branded types or passed a schema:

// Unsafe. The value becomes SQL source text.
await db.query(`SELECT * FROM users WHERE id = '${userId}'`);

A UUID validation rule may reduce risk in one path. It does not make interpolation a safe convention. Validation rules change, other inputs may have weaker constraints, and escaping varies by database and driver.

Dynamic identifiers need an allow-list

Placeholders generally cannot represent SQL identifiers or keywords. If an endpoint supports sorting by selected columns, construct that fragment only from source-owned literals.

const sortColumns = {
  createdAt: "created_at",
  name: "name",
} as const;

type SortKey = keyof typeof sortColumns;

function parseSortKey(value: unknown): SortKey {
  if (value === "createdAt" || value === "name") {
    return value;
  }

  return "createdAt";
}

const sortKey = parseSortKey(req.query.sort);
const sortColumn = sortColumns[sortKey];

const result = await db.query(
  `SELECT id, name FROM projects WHERE tenant_id = $1 ORDER BY ${sortColumn} ASC`,
  [tenantId],
);

The request controls a known key, not arbitrary SQL. Apply the same approach to sort direction, table selection, and other dynamic SQL fragments.

Treat HTML as a runtime trust boundary

Most rendering should use framework escaping. React escapes strings rendered in JSX by default:

<div>{comment.body}</div>

The risk appears when an application intentionally renders HTML, such as rich-text content or imported documentation. Raw user HTML must not reach dangerouslySetInnerHTML without a reviewed sanitization step.

A brand makes the distinction visible:

declare const sanitizedHtmlBrand: unique symbol;

type SanitizedHtml = string & {
  readonly [sanitizedHtmlBrand]: true;
};

The brand alone has no security value:

const unsafe = input as SanitizedHtml;

That cast only changes the compile-time label. The constructor must run a maintained sanitizer with an application-specific policy.

For Node.js or server-side rendering, DOMPurify needs a DOM implementation. The following setup uses JSDOM:

import createDOMPurify from "dompurify";
import { JSDOM } from "jsdom";

const window = new JSDOM("").window;
const DOMPurify = createDOMPurify(window);

function sanitizeHtml(input: string): SanitizedHtml {
  const clean = DOMPurify.sanitize(input, {
    ALLOWED_TAGS: ["p", "a", "strong", "em", "ul", "ol", "li", "code", "pre"],
    ALLOWED_ATTR: ["href"],
  });

  return clean as SanitizedHtml;
}

The rendering component can require sanitized content:

function RichText({ html }: { html: SanitizedHtml }) {
  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

Keep the sanitizer factory server-only when using SSR. Browser bundles can initialize DOMPurify with the browser window object instead.

Sanitizer settings are security-sensitive code. Review allowed tags, attributes, URL protocols, CSS handling, embedded content, and server-rendering behavior. Keep DOMPurify and JSDOM updated. If the product does not need arbitrary HTML, use Markdown with a restricted renderer or a structured rich-text format.

Adopt the pattern without type theater

Security-focused types lose value when every escape hatch is open. any, broad as casts, non-null assertions, and generic conversion helpers can erase the protections. Some are necessary at isolated interoperability boundaries. They should not be the usual way to satisfy the compiler.

Start at boundaries with direct security consequences:

HTTP responses and logs: Add response DTOs and named log events for user, payment, admin, and tenancy data.
Tenant-scoped access: Introduce distinct identifiers where swapped values or missing scope could expose another customer’s data.
External inputs: Parse request bodies, webhooks, queues, and environment values with runtime schemas.
SQL access: Standardize parameterized database APIs and fixed allow-lists for dynamic identifiers.
Rich-text rendering: Keep raw and sanitized HTML separate, with one narrow sanitization module.

Do not brand every string. A CurrencyCode, TenantId, or SanitizedHtml type justifies its maintenance cost when mixing it with another value can create a real bug. A type used everywhere but protecting nothing adds friction without improving review quality.

Enforce conventions with tooling and tests

Compiler settings help expose unsafe assumptions:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true
  }
}

These options are not security controls. They reduce ambiguity around undefined, optional fields, and inheritance, making boundary code easier to reason about.

Use linting and review rules for dangerous escape hatches. Examples include requiring justification for as, prohibiting any outside approved modules, and flagging direct model serialization in controllers. Keep exceptions narrow and documented.

Test what types cannot prove:

An authenticated user cannot read or modify another tenant’s resource.
Sensitive columns do not appear in real HTTP responses or logs.
Webhook verification occurs before payload use.
SQL repository methods retain tenant predicates.
Sanitized rich text rejects unsafe URLs and event handlers.
Role changes and revoked memberships take effect as expected.

Integration tests should exercise real middleware, serializers, and database paths. Mapper unit tests help, but integration tests catch endpoints that bypass the mapper.

Key takeaways

TypeScript improves application security when it represents meaningful boundaries.

Return explicit response DTOs rather than persistence objects. Allow-list fields that may leave the service.
Create dedicated log events and redaction functions. Do not log arbitrary models or request bodies.
Use branded identifiers for values that must not be mixed, especially in tenant-scoped code.
Model verified authority with capability types, but check authorization from trusted state for every relevant request.
Parse external values at runtime before treating them as domain input.
Keep SQL parameterized. Use fixed source-owned allow-lists for dynamic identifiers.
Escape HTML by default. Sanitize only when rendering HTML is required.
Back type design with integration tests, database constraints, dependency maintenance, monitoring, and security review.

Explicit DTOs, scoped identifiers, narrow authority-bearing APIs, and visible trust conversions make unsafe flows easier to spot during implementation and review. They do not replace runtime defenses. They reduce the chance that ordinary application mistakes bypass those defenses.

References

Architecture from Day One: The Practical Guide to Scalable Backend Systems

Shubham — Sun, 19 Jul 2026 05:20:11 +0000

Every backend engineer wants to build systems that scale. But scalability is not a feature to casually bolt onto version 2.0; it is an emergent property of deliberate architectural choices, operational discipline, and evidence from real workloads.

After years of building and operating high-throughput systems across fintech and aviation, these are the foundational principles and production patterns that matter when moving from thousands of users to millions.

1. Define “scalable” beyond the buzzwords

Scaling is not simply handling more users. It is maintaining an agreed level of service as load grows: latency, correctness, availability, and cost all matter. A system that works for 1,000 users but collapses at 10,000 has a bottleneck to understand not merely “high load.”

A practical rule: do not judge scalability by raw requests per second alone. Define SLOs, then observe latency at the tail (especially p95 and p99), error rate, and resource saturation as load increases. A flat median can conceal a failing tail.

Run load tests that resemble production: realistic request mixes, payloads, connection behavior, data sizes, and downstream dependencies. Track queue depth, CPU, memory, database connections, disk and network saturation alongside user-facing SLOs. The useful question is: at what load do the SLOs, error budget, or cost envelope stop being acceptable?

Horizontal and vertical scaling: choose with evidence

Vertical scaling is often the fastest, safest next step. A larger database instance, more memory for a cache, or a faster machine can be appropriate until availability, failure-domain, or cost limits make it unattractive. Horizontal scaling adds capacity and resilience, but also coordination, deployment, and consistency complexity.

Stateless services: scale horizontally when demand and redundancy justify it.
Stateful services: first optimize queries, indexes, schema, and instance sizing; use replicas, partitioning, or sharding when measurements show they are needed.
Mixed workloads: separate stateful and stateless responsibilities so each can be tuned and scaled independently.

Sharding is not a default milestone. It raises operational and application complexity routing, rebalancing, cross-shard queries, and recovery. Introduce it only when observed data volume, write throughput, storage, or availability requirements exceed what simpler approaches can meet.

2. Stateless design enables elastic application capacity

Keeping request-specific state out of application memory makes ordinary HTTP request handling easier to distribute across instances. Sessions, shared rate-limit counters, and durable workflow state should live in purpose-built external stores rather than a process-local map.

// Bad: process-local session state is lost on restart and is not shared.
const sessions = new Map<string, Session>();
function getSession(id: string) {
  return sessions.get(id);
}

// Better: use a shared store with expiry and appropriate availability controls.
async function getSession(id: string) {
  return redis.get(`session:${id}`);
}

Statelessness does not mean every instance can be terminated without coordination. WebSockets, server-sent events, streaming responses, in-flight requests, local uploads, and long-running jobs may still be attached to an instance. Use readiness checks and graceful draining: stop accepting new work, allow bounded in-flight work to finish, notify or reconnect long-lived clients when appropriate, and enforce a termination deadline. Sticky routing may still be useful for connection affinity or performance, even if it is not required for ordinary shared-session HTTP traffic.

3. Multi-layer caching without correctness surprises

Caching is high leverage for read-heavy workloads, but its common risks are stale reads, inconsistent invalidation, cache-key mistakes, eviction behavior, and thundering herds not an automatic guarantee of data corruption or split brain. Treat the backing datastore as the source of truth unless you have explicitly designed a stronger consistency model.

Cache layer

Typical targets

Useful characteristics

Edge / CDN

Public, cacheable assets and responses

Low latency near users; deliberate cache-control and purge strategy

Application / distributed cache

Derived objects, sessions, rate limits

Shared across instances; explicit TTLs, keys, and invalidation

Database buffer / replicas

Frequently read database pages and read traffic

Helps throughput, but replicas can have replication lag

Choose a pattern deliberately: cache-aside is simple for many reads; write-through can reduce stale-cache windows; write-behind trades simplicity for durability and recovery concerns. Version cache keys when schemas change, invalidate or update entries on writes, and set bounded TTLs even when invalidation exists.

Protect the origin from a cache stampede. Coalesce concurrent misses with request locking or single-flight, refresh hot entries ahead of expiry where suitable, and add jitter to TTLs so many keys do not expire together. Monitor hit rate, miss rate, eviction, keyspace growth, memory pressure, origin fall-through, refresh failures, and stale-serving behavior. Test failure modes: cache unavailable, invalidation delayed, and an expired hot key under peak traffic.

4. Data scaling and the CAP theorem

Replication improves read capacity and resilience, but it introduces lag and failover trade-offs. Route reads only where the consistency required by the operation is available; a user who has just written data may need read-your-writes behavior rather than an asynchronous replica.

CAP is specifically about what a distributed system does during a network partition. When replicas cannot communicate, a system cannot simultaneously guarantee both a single consistent view of data and availability of every request. The design chooses its behavior per operation: reject or block some requests to preserve consistency, or serve potentially stale/divergent data and reconcile later. Outside a partition, latency, quorum configuration, and implementation choices still determine practical behavior.

Use evidence before introducing partitions or shards: sustained write bottlenecks, storage limits, noisy-neighbor isolation, geographic requirements, or demonstrated availability needs. Define a shard key that spreads traffic, avoid cross-shard transactions where possible, and plan rebalancing, backups, and repair before the first shard is created.

5. Control overload at every boundary

Load balancers distribute traffic; they do not create infinite capacity. Set connection and concurrency limits at services and dependencies, and propagate deadlines so doomed work does not continue consuming resources. Timeouts should be explicit and shorter than the caller’s remaining deadline.

Backpressure and load shedding: bound queues, reject low-priority work early, and return clear overload responses instead of allowing unbounded latency and memory growth.
Retries: retry only operations that are safe or idempotent; use exponential backoff with jitter, a maximum attempt count, and a retry budget so an incident does not become a retry storm.
Circuit breakers: temporarily stop calls to a demonstrably unhealthy dependency, fail fast or use a defined fallback, and probe recovery carefully.
Bulkheads: isolate thread pools, connection pools, queues, and tenant limits so one slow dependency or customer does not exhaust the whole service.

Instrument saturation and queueing, not only successful request rate. Alert on SLO burn, p95/p99 regressions, error rate, exhausted pools, queue age, and dependency health.

6. Event-driven architecture needs delivery discipline

Event-driven architecture (EDA) can decouple producers from consumers and smooth bursty work, but a broker does not remove distributed-systems failure modes. Most practical consumers operate with at-least-once delivery, so duplicates are normal rather than exceptional.

Make handlers idempotent using stable event IDs, deduplication records, or idempotent writes.
Retry transient failures with bounded exponential backoff and jitter; send poison messages to a monitored dead-letter queue (DLQ) with a replay process.
Document ordering scope. Ordering may exist only within a partition/key, and retries can change the apparent order.
Use the transactional outbox pattern when a database write and event publication must not diverge. Persist the intent with the business transaction, then reliably relay it to the broker.
Version event schemas and preserve compatibility during producer and consumer rollouts.

Measure lag, consumer throughput, retry counts, DLQ volume, duplicate rate, and end-to-end processing latency. These metrics turn “asynchronous” into an observable service commitment.

7. Build the feedback loop

Capacity planning is a continuous loop: establish SLOs, instrument real workloads, test failure and load scenarios, remove the measured bottleneck, and repeat. Prefer the simplest architecture that meets current reliability and growth needs, while leaving clean seams for the next proven constraint.

Scalable systems are not the ones with the most components. They are the ones that make trade-offs explicit, degrade predictably under stress, and give operators enough observability to act before customers notice.

How I Built a Personal AI Assistant That Lives in Telegram

Shubham — Sun, 19 Jul 2026 05:15:49 +0000

I wanted a personal AI assistant that lived where I already communicate: Telegram. Not another dashboard to remember, not a browser tab that disappears into the pile, and not a demo that can write clever text but cannot actually help me do things.

The result is a Telegram bot that can answer questions, remember useful context, schedule reminders, retrieve information, and use connected services through tightly controlled tools. It is intentionally practical rather than magical. The interesting work was not making a model produce text; it was building the systems around it so that tool use, scheduling, failures, and external side effects behave predictably.

This post explains the architecture, the trade-offs I made, and the safeguards that make a personal assistant useful without turning it into an unattended automation machine.

What I Optimized For

Telegram-first interaction: send a message, receive a useful response, and avoid a separate product surface.
Tool use with boundaries: it can retrieve data and invoke integrations, but it cannot freely perform side effects.
Durable personal state: reminders, notes, job history, and operational records must survive restarts.
Simple operations: one deployable service, observable logs, backups, and understandable failure modes.
Honest scaling limits: start with SQLite and one active bot consumer; change the architecture only when the workload requires it.

I did not optimize for a fully autonomous agent. For a personal assistant, reliability and control are more valuable than letting a model take unlimited actions.

Architecture Overview

At a high level, the system has five layers:

Telegram ingress: Telegraf receives updates and normalizes messages into an application request.
Conversation orchestration: the application loads relevant context, calls OpenAI, and runs a bounded tool-execution loop.
Tool layer: local capabilities such as notes, reminders, weather, and database reads sit behind explicit schemas and policies. Connected third-party services are accessed through Composio.
Durable state: SQLite stores sessions, scheduled jobs, execution attempts, idempotency keys, and operational data.
Background worker: a scheduler claims due jobs, executes them, records the result, and retries safely where appropriate.

Telegram
   │
   ▼
Telegraf handler ──► auth + rate limits ──► assistant orchestrator
                                              │
                         ┌────────────────────┼────────────────────┐
                         ▼                    ▼                    ▼
                     OpenAI API          local tools           Composio
                         │                    │                    │
                         └──────────────► SQLite ◄─────────────────┘
                                               ▲
                                               │
                                        scheduler worker

The application is deliberately not a collection of unconstrained agents talking to each other. A single orchestrator owns the request lifecycle. That makes it easier to trace what happened, apply policy consistently, and keep failures from becoming confusing.

Why Bun, Telegraf, OpenAI, Composio, and SQLite

I chose Bun because it gives me a fast TypeScript runtime, package management, and a straightforward deployment target. It keeps the service compact without requiring a complicated build pipeline for a small application. Bun is not the reason the assistant is reliable, though; explicit application boundaries and durable state are.

Telegraf is a mature, ergonomic Telegram framework. It handles the Telegram update format well while leaving routing, middleware, and error handling under my control. The bot layer should be boring: validate the sender, acknowledge the message lifecycle, and hand work to the application layer.

OpenAI provides the language model and structured tool-calling interface. Tool definitions help the model select an operation and produce arguments in an expected shape. They do not replace runtime validation. The model can still select an inappropriate tool, provide malformed data, or request an action the current user should not be allowed to take.

Composio is useful for OAuth-backed integrations. Instead of implementing every third-party OAuth flow, token lifecycle, and API wrapper myself, I can use a consistent connection layer for supported external services. That convenience does not eliminate security work: every integration still needs an allowlist, narrow scopes, and separate treatment for read operations versus side effects.

SQLite is the right database while the assistant is a single-user or low-volume system. It is portable, inexpensive to operate, and excellent for transactional local state. I use it for data that must be durable: reminders, job execution records, sessions, and idempotency keys. It is not a distributed queue, and it is not the long-term answer for multiple independently writing application instances.

Polling Instead of Webhooks

I use Telegram long polling rather than webhooks. For a personal deployment, polling avoids exposing a public HTTPS endpoint, certificate management, reverse-proxy setup, and webhook routing. The process asks Telegram for updates, processes them, and advances through the update stream.

The important caveat is that polling needs exactly one active consumer for a bot token. Running two polling instances at once can create conflicts and unpredictable update handling. If I deploy a replacement instance, I make sure the previous consumer is stopped before the new one begins polling.

Offset handling matters too. Telegram updates have monotonically increasing identifiers, and the consumer must advance its offset only after it has safely recorded or processed an update. In practice, I also keep a durable update or message idempotency record. That protects against duplicate handling after a process crash, a network timeout, or a restart near the boundary between receiving and committing an update.

const seen = db.query(
  "SELECT 1 FROM processed_updates WHERE update_id = ?"
);

async function handleUpdate(update: TelegramUpdate) {
  if (seen.get(update.update_id)) return;

  db.run("BEGIN IMMEDIATE");
  try {
    db.run(
      "INSERT INTO processed_updates (update_id, processed_at) VALUES (?, ?)",
      [update.update_id, new Date().toISOString()]
    );
    db.run("COMMIT");
  } catch (error) {
    db.run("ROLLBACK");
    throw error;
  }

  await processMessage(update);
}

The exact transaction design depends on what is being processed, but the principle is consistent: duplicate delivery is normal in distributed systems, so handlers should be safe to run more than once.

From Message to Tool Call to Reply

When a Telegram message arrives, the bot does not immediately hand raw text to a model and execute whatever comes back. The request follows a controlled pipeline:

Verify that the chat and user are permitted to use the assistant.
Apply per-user and global rate limits.
Load the minimum relevant conversation context and persistent memory.
Send the model a system policy, the user message, and a small allowlisted tool catalog.
Validate every requested tool call against a runtime schema and authorization policy.
Execute approved tools, append structured results, and continue the model loop within a strict step limit.
Persist useful state and send the final answer back through Telegram.

The model loop is intentionally bounded. A tool-capable model can ask for another tool result after receiving the previous one, so a useful assistant needs multiple steps. But it also needs a ceiling to prevent accidental loops, excessive API cost, or an unexpected chain of actions.

const MAX_TOOL_STEPS = 5;

for (let step = 0; step < MAX_TOOL_STEPS; step++) {
  const response = await openai.responses.create({
    model: MODEL,
    input,
    tools: allowedToolsFor(user),
  });

  const calls = extractToolCalls(response);
  if (calls.length === 0) {
    return extractText(response);
  }

  for (const call of calls) {
    const result = await runApprovedTool({
      userId: user.id,
      chatId: chat.id,
      call,
    });

    input.push(toolResultMessage(call, result));
  }
}

throw new Error("Tool loop exceeded its configured limit");

I also set timeouts at the boundaries: Telegram delivery, model requests, database operations, and external integrations. One slow provider should not hold a message handler forever.

A Safe Tool Policy

Tool calling is where an assistant becomes useful and where it can become unsafe. My policy is based on capability rather than prompt wording.

First, tools are allowlisted. The model sees only tools appropriate for the current user and context. A read-only stock quote tool, for example, is fundamentally different from a tool that sends an email or creates a calendar event. I do not expose administrative or infrastructure operations to a general chat flow just because the model could describe them.

Second, every tool has runtime argument validation. TypeScript types are useful during development, but they disappear at runtime. Tool arguments from a model or an external API are untrusted input. I validate them with a schema library or explicit checks before calling application code.

const createReminderSchema = z.object({
  task: z.string().min(1).max(500),
  time: z.string().regex(/^\d{2}:\d{2}$/),
  scheduleType: z.enum(["once", "daily", "weekdays", "weekly"]),
  dayOfWeek: z.string().optional(),
});

function validateReminder(args: unknown) {
  return createReminderSchema.parse(args);
}

Third, external side effects require explicit confirmation. If the assistant is about to send a message, create an event, modify a document, or perform another consequential action, it prepares a preview and asks the user to confirm. A confirmation is tied to the intended action, expires quickly, and is consumed once. The system should not interpret “yes” from an unrelated later conversation as approval to send something.

Fourth, side-effecting operations receive an idempotency key. A network failure after a provider accepts a request is ambiguous: retrying without a key can create duplicate events, emails, or tasks. Where a provider supports idempotency, I pass a stable key. Where it does not, I persist an operation record and use provider-specific lookup or reconciliation where possible.

Finally, OAuth connections are scoped and isolated. I request the narrowest permissions needed, avoid broad account access by default, store connection references rather than casually exposing raw tokens, and make disconnecting an integration straightforward. Secrets belong in the deployment environment or a secret manager, never in source control, logs, prompts, or tool output.

SQLite, WAL, and Scheduling Correctness

I run SQLite in write-ahead logging mode:

PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
PRAGMA busy_timeout = 5000;

WAL improves concurrency for this workload because readers can continue while a writer is committing. It does not turn SQLite into a multi-writer database. There is still one writer at a time, so transactions should be short, indexes should support the scheduler’s queries, and write-heavy background work should not be mixed carelessly with long interactive transactions.

The scheduler stores jobs in SQLite rather than trusting in-memory timers. A worker periodically finds due jobs, atomically claims one, runs it, and records the outcome. The claim prevents two worker loops from executing the same job simultaneously in the same database.

UPDATE scheduled_jobs
SET status = 'running',
    locked_at = :now,
    lock_token = :token
WHERE id = (
  SELECT id
  FROM scheduled_jobs
  WHERE status = 'pending'
    AND run_at <= :now
  ORDER BY run_at
  LIMIT 1
)
AND status = 'pending';

A worker is not a durable queue merely because it runs in a loop. Durability comes from the database records: pending jobs, attempts, lock timestamps, completion state, and idempotency keys. If the process dies after claiming a job, recovery logic detects stale locks and returns eligible work to the pending state. If the process dies after an external side effect but before recording completion, idempotency and reconciliation logic determine whether it is safe to retry.

For recurring jobs, I calculate the next run after a successful execution and store times consistently, typically in UTC with the user’s timezone retained for display and recurrence rules. Timezones and daylight-saving transitions deserve dedicated tests; “every day at 9” is more complicated than adding 24 hours.

Error Handling, Rate Limits, and Operations

Every integration can fail. Telegram can time out, an OAuth token can be revoked, OpenAI can rate-limit a request, and a third-party API can return malformed data. The assistant should explain failures plainly without leaking secrets or internal stack traces.

I categorize errors into retryable and non-retryable classes. Network timeouts, temporary 429 responses, and many 5xx errors can be retried with exponential backoff and jitter. Invalid arguments, revoked permissions, and user-denied confirmations should not be blindly retried. Retries have caps, deadlines, and structured logs so a bad provider does not create an infinite background loop.

Rate limits exist at multiple layers: Telegram message handling, model calls, tool calls, and external APIs. For interactive chat, a per-user token bucket or short rolling window is usually sufficient. I also limit tool-loop depth, tool-call count, payload size, and concurrent outbound requests. These controls protect both cost and availability.

Deployment is intentionally simple: one application instance, persistent storage mounted outside ephemeral container layers, environment-based configuration, and a process supervisor or platform health checks. Before each deploy, I run migrations in a controlled step and ensure the prior polling consumer has stopped. Health checks verify that the process is alive; readiness checks should also verify that configuration and the database are usable.

Backups are not optional because SQLite is the system of record. I take regular backups from a consistent SQLite snapshot, retain multiple recovery points, encrypt backups where appropriate, and periodically test restoration. A backup that has never been restored is only a theory.

Tests, Observability, and Scaling Boundaries

The highest-value tests are not model snapshot tests. They cover authorization decisions, runtime validation, confirmation expiry, idempotency, scheduler claims, stale-lock recovery, timezone behavior, and duplicate Telegram updates. I use mocked provider clients for deterministic unit tests, then run a small number of integration tests against isolated credentials or test resources.

For observability, each incoming Telegram update receives a correlation id. Logs include the update id, user or chat identifier where safe, request duration, model request id when available, tool name, retry count, and job id. I record metrics for error rates, latency, tool failures, queue age, worker recovery, and rate-limit rejections. I log metadata, not secrets or private message content by default.

This architecture has clear scaling boundaries. SQLite with one active polling process is excellent for a personal assistant and modest traffic. It becomes a constraint when multiple application instances need concurrent writes, background work grows significantly, or webhook-based horizontal ingress becomes necessary. At that point, I would move durable state to a server database such as Postgres and use a real queue for independently scalable workers. I would not pretend that adding more containers around one SQLite file solves distributed coordination.

Build Checklist

Create a Telegram bot and restrict initial access to known user or chat ids.
Start with Telegraf long polling and ensure only one consumer runs at a time.
Build a small OpenAI orchestration loop with a maximum number of tool steps.
Expose only an explicit, per-user allowlist of tools.
Validate every tool argument at runtime before execution.
Split read-only tools from side-effecting tools; require preview and confirmation for the latter.
Use scoped OAuth connections and keep credentials out of code, prompts, and logs.
Persist jobs, attempts, locks, and idempotency keys in SQLite.
Enable WAL, keep write transactions short, and plan around SQLite’s single-writer model.
Implement stale-lock recovery and bounded retry behavior for workers.
Add structured logs, metrics, alerts, and restoration-tested backups.
Test duplicates, retries, revocations, crashes, and timezones before relying on automation.

Repository and Implementation Notes

The implementation evolves, but the core idea remains stable: keep the chat interface simple and put the engineering effort into policy, persistence, and recoverability.

View the project source on GitHub.

Conclusion

A useful personal AI assistant is less about giving a model unlimited access and more about designing reliable boundaries around it. Telegram provides the interface, OpenAI provides reasoning and language, Composio can provide controlled access to connected services, and SQLite provides a durable foundation for a small deployment.

The hard parts are familiar engineering problems: authorization, input validation, duplicate delivery, idempotency, retries, recovery, backups, and observability. Solving those deliberately turns an impressive chatbot demo into an assistant I can trust to use every day.

What's All Am I Hosting? Full Infrastructure Breakdown

Shubham — Sat, 04 Jul 2026 18:52:41 +0000

Every few months, someone asks me how I run my entire online presence for basically nothing. The short answer is: I don't pay for what I can get for free.

The long answer is this post.

My entire infrastructure this site, APIs, email, monitoring, URL shortener, dev tools runs on free-tier cloud services. Total cost: $0/month. That's less than a single AWS load balancer costs for an hour.

Here's exactly how it works, why I chose each piece, and what I'd do differently.

The Philosophy: Free Tier First

I have a simple rule: if a service has a generous free tier that covers my use case, I use it. If I outgrow it, I'll pay but most of us never outgrow free tiers for personal projects.

The second rule: own the critical paths. DNS is the backbone, so it's on Cloudflare (free, but best-in-class). The main site is on Vercel (free, seamless Next.js deployment). Everything else databases, email, APIs, monitoring is a managed service that solves exactly one problem well.

DNS: Cloudflare (The Glue That Holds It All Together)

Everything starts with DNS. Cloudflare runs chan.ns.cloudflare.com and dave.ns.cloudflare.com as my authoritative nameservers. Every subdomain in this post is a DNS record that Cloudflare serves for free.

I use Cloudflare as a pure DNS provider no CDN proxying on most records except a few redirects (cal, link, mail). The proxied records hide my origin IP and give me free SSL termination, but I keep most records direct because I want full control over the traffic path.

Why Cloudflare over Route53 or self-hosted? Cloudflare's free plan includes unlimited DNS queries, DNSSEC, easy API access, and their dashboard is fast. Route53 charges per query. Self-hosting DNS is unnecessary complexity. Free + best-in-class = no contest.

The Main Site: Vercel

shubhkumar.in is hosted on Vercel's free tier. The apex domain uses an A record to 216.198.79.1 (Vercel's anycast IP for apex domains you can't use a CNAME at the root).

Vercel's free tier includes 100GB bandwidth, 6000 build minutes, automatic SSL, and edge network distribution. For a Next.js site with ISR, this is more than enough. The site loads fast everywhere because Vercel serves it from their edge network.

The www subdomain CNAMEs to the root standard practice.

Other Vercel-Hosted Sites

cv.shubhkumar.in Resume site. Next.js, deploys from GitHub.
news.shubhkumar.in Another Next.js site.

Hosted Applications: The Free Tier Dream Team

Render API Server

api.shubhkumar.in runs on Render's free tier. It handles contact forms, webhooks, and server-side endpoints the static site can't handle. Render gives 750 hours/month plenty for a low-traffic personal API.

Why Render over Railway or Fly.io? Render has the most generous free tier for this use case. The deploy experience is smooth (Git push → deploy), and SSL is automatic.

GitHub Pages Lightweight Pages

connect.shubhkumar.in is a simple social link aggregator Linktree-style but self-hosted. Single HTML page, zero cost, instant deploy from a GitHub repo.

Infrastructure: The Stuff That Runs in the Background

Tailscale Private Network Bridge

tail.shubhkumar.in points to my Tailscale node at 100.115.133.19. Tailscale creates a WireGuard mesh across all my devices laptop, home server, cloud VMs. The DNS record lets me reach my home lab from anywhere using a proper subdomain.

The real magic: Tailscale handles NAT traversal automatically. My home server is behind CGNAT (common with Indian ISPs), and Tailscale punches through without any port forwarding. Free tier: up to 100 devices.

Databases Managed, Never Self-Hosted

I use managed databases exclusively. Supabase (Postgres) for anything that needs relational queries and real-time subscriptions. MongoDB Atlas for document storage when the schema is fluid. Both on free tiers or their cheapest paid plans whichever covers the workload.

Self-hosting a database is the fastest way to turn a weekend into an ops nightmare. Backups, replication, patches, disk space all someone else's problem. The managed premium is worth every rupee.

Fly.io Lightweight Apps

track.shubhkumar.in hosts WakaAPI (self-hosted WakaTime stats) on Fly.io. Free allowance covers the tiny resource usage 3 shared-CPU VMs with 256MB RAM, 3GB storage, 160GB outbound.

Cal.com Scheduling

cal.shubhkumar.in Cloudflare-proxied redirect to Cal.com. Self-hosting a calendar scheduler isn't worth my weekend.

Better Uptime Monitoring

status.shubhkumar.in Free tier. Monitors all endpoints, notifies on Slack. 10 monitors with 3-minute checks and a public status page.

Tools and Redirects

Dub.co URL Shortener

go.shubhkumar.in runs on Dub.co's free tier. Short, memorable links go.shubhkumar.in/github, etc. Open-source, great API, free tier includes custom domains and basic analytics.

Used to run YOURLS on a VPS. Moving to Dub.co saved maintenance and gave better analytics.

Simple Redirects

link.shubhkumar.in and mail.shubhkumar.in are Cloudflare-proxied redirects using 192.0.2.1 (Cloudflare's placeholder IP). No server needed Cloudflare page rules handle the redirects.

Email Infrastructure: The Hardest Part

Email is the hardest thing on a personal domain. I run three services for different purposes because each solves a specific problem.

Zoho Mail Primary

Primary email on Zoho's free plan 5 mailboxes with 5GB each, custom domain, IMAP/SMTP, calendar. The last remaining free tier for professional email on a custom domain after Outlook killed their free custom domain offering and Google Workspace charges $6/user/month.

MX: mx.zoho.com (priority 10), mx2/3 as fallbacks. DMARC set to reject with Cloudflare reporting.

Trade-off: Zoho's spam filtering is decent but not Gmail-level. For free, acceptable.

SimpleLogin Email Aliases

simple.shubhkumar.in Creates aliases that forward to my primary inbox. If a service sells my email, I delete the alias. Free tier: 15 aliases, PGP encryption, open-source.

Resend Transactional + Broadcast Emails

I use Resend for all outgoing emails transactional notifications, broadcast newsletters, and contact form submissions. It handles everything through a single clean API with good deliverability out of the box.

Resend's free tier includes 100 emails/day, which covers my low-volume needs. DKIM and SPF configured through forms.shubhkumar.in for proper authentication.

Security and Verification Records

DMARC (reject) Strictest policy. Reports to Cloudflare's DMARC reporting. Caught email spoofing attempts at least twice.
BIMI Shows my logo next to authenticated emails. Mostly vanity but looks professional.
Keybase Domain ownership proof.
Google Search Console Site ownership for search analytics.

What I Don't Use (And Why)

No Kubernetes. Everything fits in docker-compose or managed platforms. K8s is operational overkill for one person.
No AWS. Pricing model punishes hobbyists. One misconfigured resource = surprise bill. I use SES for email only when necessary.
No self-hosted CI. GitHub Actions is free for public repos.
Databases: Managed Supabase (Postgres), MongoDB Atlas, etc. Free tiers + cheapest plans cover everything. Self-hosting a database is unnecessary ops overhead.

Cost Breakdown

Service

Cost

What It Runs

Vercel

Main site (Next.js) + CV + News

Cloudflare DNS

All DNS records, proxied redirects

Render

API server

GitHub Pages

Link aggregator

Fly.io

WakaAPI instance

Better Uptime

10 monitors, status page

Dub.co

URL shortener

Zoho Mail

Primary email, custom domain

SimpleLogin

15 email aliases

Resend

Transactional + broadcast emails

Tailscale

Mesh VPN, 100 devices

Supabase

Managed Postgres (free tier)

MongoDB Atlas

Managed MongoDB (free tier)

Total

$0/mo

~15 services, one domain, full infra

Lessons Learned

You don't need to self-host everything. Used to run my own email server, Git server, CI huge time sink for zero benefit. Managed services let you focus on what matters.
DNS TTL matters. Low TTL (1–300s) on frequently changed records. High TTL (86400) on stable records for faster lookups.
Email deliverability is a second job. DKIM + SPF + DMARC + BIMI + reverse DNS + feedback loops takes a full day to set up. Get it right once, don't touch it.
Free tiers are designed to hook you. That's fine as long as you understand the migration cost before you're locked in.
Monitoring is not optional. Better Uptime caught three outages I wouldn't have noticed until someone emailed me.

The Reality

Running your own infrastructure is a trade-off setup time and occasional debugging for complete control and zero ongoing cost. For me, it's worth it.

But I also know when to stop. I don't self-host email. I don't run a Docker registry. I don't build custom dashboards. The services I chose handle those well enough that my time is better spent building on top of them.

Building My Personal Website From Scratch: Tech Stack, Architecture, and Lessons Learned

Shubham — Sat, 27 Jun 2026 19:12:59 +0000

A personal website is more than just a portfolio it's a playground for experimenting with architecture, performance, and production-ready engineering.

Introduction

Ask ten software engineers what their personal website is for, and you'll probably hear the same answer: "It's my portfolio."

While that's true, I wanted mine to be something more.

I wanted shubhkumar.in to be a platform that could grow with me a place to showcase projects, host my CV, publish technical blogs, and experiment with ideas before applying them in production systems.

Rather than using a static template or website builder, I decided to build everything from scratch. My goal wasn't to use the most technologies possible; it was to create a clean architecture that was fast, maintainable, and easy to extend.

Today, the website consists of two main parts:

A Next.js frontend deployed on Vercel
A Node.js + Express backend deployed on Render

Behind the scenes, MongoDB stores dynamic content, while Redis speeds up API responses through caching.

It sounds like a fairly standard stack and in many ways, it is. But the interesting part wasn't choosing the technologies. It was designing how they work together.

Why Build It From Scratch?

There are countless templates and portfolio generators available today. They look great, take minutes to deploy, and require almost no maintenance.

So why spend time building everything yourself?

For me, the answer was simple.

I wanted complete control.

Not just over the design, but over the architecture.

I wanted a backend that wasn't tightly coupled to a frontend. I wanted my content to live in one place instead of being duplicated across pages. Most importantly, I wanted a project that reflected how I build software professionally.

Every new feature became an opportunity to solve a real engineering problem instead of simply adding another section to a webpage.

The Tech Stack

I deliberately kept the stack simple.

Frontend

Next.js
Tailwind CSS
Hosted on Vercel

Next.js gives me everything I need for a modern website:

Server Components
Static rendering
Excellent SEO
Fast routing
Built-in image optimization
Incremental Static Regeneration (ISR)

Tailwind CSS keeps styling consistent without maintaining a large CSS codebase.

Deploying to Vercel makes the frontend almost effortless. Every push automatically builds and deploys the latest version.

Backend

Instead of relying on Next.js API routes, I built a dedicated backend using:

Node.js
Express
Hosted on Render

This backend acts as the single source of truth for all dynamic content.

Whether it's:

portfolio information
experience
projects
resume data
future APIs

everything is served from one backend.

Keeping the backend independent means it can later power:

a mobile app
an admin dashboard
CLI tools
browser extensions
or any future frontend

without changing business logic.

Database

Dynamic content is stored in MongoDB.

Documents include:

Profile information
Experience
Skills
Projects
Portfolio data

Interestingly, blog posts are not stored in MongoDB. They are maintained separately, allowing the website content and blog content to evolve independently.

Caching

To reduce unnecessary database queries, the Express API caches responses in Redis.

The flow looks like this:

Client
   │
   ▼
Express API
   │
   ▼
Redis
   │
Cache Hit?
   │
 ┌─┴─────────────┐
 │               │
Yes             No
 │               │
 ▼               ▼
Return      MongoDB
Response        │
                ▼
          Store in Redis
                │
                ▼
          Return Response

Most requests never reach MongoDB.

This keeps API responses fast while reducing database load.

Overall Architecture

At a high level, the system looks like this.

                 +----------------------+
                 |      Next.js         |
                 |   Hosted on Vercel   |
                 +----------+-----------+
                            |
                            |
                     HTTP Requests
                            |
                            ▼
                +----------------------+
                |   Express Backend    |
                |   Hosted on Render   |
                +----------+-----------+
                           |
               +-----------+-----------+
               |                       |
               ▼                       ▼
        Redis Cache             MongoDB Atlas

Although there are multiple services, each one has a single responsibility.

Next.js renders pages.
Express serves business logic.
Redis caches responses.
MongoDB stores data.

Keeping responsibilities separate makes the system easier to reason about and easier to extend.

Why I Didn't Use Next.js API Routes

This was probably the architectural decision that influenced the project the most.

Many Next.js applications place all backend logic directly inside API routes.

There's absolutely nothing wrong with that approach.

But I wanted something reusable.

By separating the backend, the frontend becomes just another client.

Tomorrow, if I decide to build:

an Android app
an iOS app
a desktop application
another website

they can all consume the exact same API.

No duplicated logic.

No duplicated validation.

No duplicated database queries.

Everything lives in one place.

Making the Backend the Single Source of Truth

The homepage.

The portfolio.

The CV.

Future applications.

All of them consume the same backend.

Instead of every page maintaining its own copy of data, everything originates from one API.

Updating my experience in MongoDB automatically updates every place where it's displayed.

This significantly reduces maintenance and prevents data from going out of sync.

The Unexpected Problem: Cache Invalidation

The most interesting problem wasn't building the website.

It was keeping it fresh.

Initially, everything looked perfect.

MongoDB stored the latest content.

Redis cached API responses.

Next.js generated static pages.

Performance was excellent.

Yet something strange happened.

Whenever I updated content, users didn't always see the changes immediately.

Sometimes it took several seconds.

Sometimes much longer.

At first, I assumed Redis was serving stale data.

After debugging for a while, I realized Redis wasn't the problem at all.

The real issue was that there were two completely independent caching layers.

The API cache and the frontend cache.

The API could already have fresh data while Next.js continued serving previously generated pages.

Everything was technically working exactly as intended.

The architecture, however, wasn't.

Solving It with Event-Driven Revalidation

Instead of waiting for caches to expire naturally, I switched to an event-driven approach.

Whenever content changes, the following sequence happens:

Admin API

      │

      ▼

Update MongoDB

      │

      ▼

Trigger Next.js Revalidation

      │

      ▼

Flush Redis Cache

      │

      ▼

Users receive fresh content

This means content updates propagate almost immediately without waiting for cache expiration.

The important lesson here is that caching is only half the problem.

The other half is knowing exactly when to invalidate that cache.

Designing a reliable invalidation strategy is often harder than adding caching in the first place.

Hosting Strategy

Keeping the frontend and backend separate also simplified deployment.

Frontend

The Next.js application is deployed on Vercel.

Benefits include:

Automatic deployments
Preview environments
Global CDN
Optimized image delivery

Backend

The Express server runs independently on Render.

Separating deployments means I can:

deploy backend fixes without rebuilding the frontend
deploy UI updates without touching backend services
scale each independently in the future

Lessons Learned

Building this website taught me several lessons that extend far beyond personal projects.

1. Simplicity scales

A small, well-structured architecture is easier to maintain than an unnecessarily complex one.

2. Separate responsibilities

Frontend rendering, backend logic, caching, and persistence all have different jobs.

Keeping those responsibilities isolated makes the system easier to evolve.

3. Build reusable APIs

The backend shouldn't exist solely for one website.

Treating it as a standalone service opens the door for future applications without additional work.

4. Cache invalidation deserves as much attention as caching

Adding Redis is easy.

Designing when and how cached data should be refreshed is where the real engineering begins.

5. Personal projects are the best place to experiment

Production systems often have strict requirements.

Personal projects provide the freedom to test ideas, refine architectures, and learn from mistakes.

Many of the lessons learned while building this website are directly applicable to larger production systems.

What's Next?

The website continues to evolve.

Some ideas I'm exploring include:

A richer admin experience for managing content
Better analytics and monitoring
Search functionality
AI-powered features
Additional APIs for future projects
More automation around content publishing

Because the architecture is modular, adding new capabilities doesn't require rewriting existing components.

That's exactly how I wanted the system to grow.

Final Thoughts

Building shubhkumar.in wasn't about creating another portfolio website.

It was about building a platform that reflects how I think about software engineering.

Choosing Next.js, Tailwind CSS, Node.js, Express, MongoDB, and Redis wasn't about following trends. It was about selecting tools that work well together while keeping the architecture clean and maintainable.

The biggest lesson wasn't learning a new framework or deploying another application.

It was realizing that good architecture isn't defined by how many technologies you use.

It's defined by how clearly each piece of the system is responsible for one job and how well those pieces work together.

If there's one takeaway I'd leave you with, it's this:

Treat your personal projects like production systems. Not because they need enterprise-scale complexity, but because they're the best place to learn the engineering practices you'll eventually use in production.

After all, the best portfolio isn't the one with the fanciest animations it's the one that demonstrates how you think as an engineer.

Moving from 60s to 6s: Latency Optimization Lessons from Functional Programming

Shubham — Wed, 24 Jun 2026 10:36:02 +0000

The broader tech community often views functional programming (FP) as an elegant academic exercise: useful for type systems, formal reasoning, and compiler guarantees, but distant from high-throughput production systems.

That framing misses something important. FP can improve the way teams model asynchronous work, failures, and state transitions. But it is not a substitute for finding the actual source of latency.

In a distributed workflow engine, we reduced observed end-to-end completion time from roughly 60 seconds to under 6 seconds for the common successful path. The primary cause was architectural: we removed repeated polling and queue wait from the synchronous execution path. PureScript and Haskell helped us express the resulting asynchronous flow explicitly and safely; they did not, by themselves, create a 10x latency improvement.

This is the engineering story behind that change, the measurements it supports, and the tradeoffs it introduced.

What the numbers mean

The 60-second and under-6-second figures are observed end-to-end timings for the workflow’s common success path, measured from request acceptance through the final response. They are not a universal service-level objective, a benchmark of every workflow type, or a claim about every percentile under every load level.

For a production latency claim, the useful view is a before/after comparison with the same workload and scope:

Scope: identical successful workflow type, including validation, business-rule evaluation, external calls, state update, and response.
Load: compare equivalent request rate, worker availability, dependency health, and database conditions.
Distribution: report p50, p95, and p99, along with sample size and the observation window, rather than relying on a single elapsed time.
Boundaries: state whether timings include client/network time, queue time, retries, and downstream-service time.

In this case, the roughly 60-second to under-6-second result should be read as an observed common-path improvement. The main lesson is diagnostic: most of the old latency was scheduled waiting, not useful computation.

The bottleneck: polling-based workflow execution

The original system used a pull-based worker architecture. Each request moved through sequential stages: validation, business-rule evaluation, external-service interactions, state transitions, and final reconciliation.

A database-backed work queue coordinated that workflow:

A worker completed a step and persisted the updated state.
A later worker polled the database for pending work.
After discovering the work, it executed the next stage and persisted the result.
The cycle continued until the workflow completed.

This design had real benefits. It made work durable, gave operators a visible recovery point, and supported retries. It also inserted a scheduling delay between stages. With several sequential transitions, those polling intervals and queue waits accumulated.

The system was not primarily compute-bound. It was wait-bound.

The architectural change: a fast path and a durable path

We separated the responsibilities that had previously been forced through one path:

Fast path: execute the request directly when the workflow can complete synchronously.
Durable path: retain queued execution for retries, recovery, delayed work, and cases that cannot safely finish inline.

A representative fast path is:

Request → Validation → Business Rules → External Service Call → State Update → Response

Instead of persisting and waiting for a poll between every step, the request continues through that chain while the required dependencies are available. Removing those handoffs is what removed the dominant source of delay.

The queue was not eliminated because it was bad. It was moved out of the successful synchronous path because its durability and scheduling semantics were unnecessary for every transition.

Where functional programming helped

PureScript’s Aff runtime gave the direct path a useful execution model: non-blocking asynchronous effects, composable sequencing, structured error handling, and cancellation/resource-safety primitives. Similar properties are available in other ecosystems; the language was an enabler, not the performance mechanism.

FP techniques improved the implementation in three practical ways:

Explicit effects: database writes, remote calls, logging, and retries are visible in the program’s effectful boundary instead of being hidden in incidental control flow.
Typed outcomes: expected failure modes can be represented as data, making it clearer which errors respond immediately, retry, or transfer to durable processing.
Composable stages: validation, rule evaluation, and external interactions can be assembled and tested as small units without scattering callback or exception handling across the workflow.

These properties made the fast path easier to reason about and operate. They did not compensate for a queueing architecture that was adding avoidable wait.

Failure handling and async decoupling tradeoffs

The direct path makes a request faster by coupling more work to the request lifetime. That tradeoff needs to be deliberate.

Queued workflows decouple producers from consumers, absorb bursts, provide durable handoff points, and allow retry/recovery to proceed after the original request has ended. A synchronous fast path gives up some of that decoupling in exchange for lower latency. It can increase pressure on downstream dependencies, expose callers to longer in-flight work, and require careful timeout, cancellation, idempotency, and backpressure policies.

The design therefore needs a clear transfer rule. When the direct path encounters a retryable failure, an unavailable dependency, a deadline risk, or work that must outlive the request, it records enough durable state and hands the workflow to the durable path. That handoff must be idempotent so a timeout or ambiguous response does not duplicate an externally visible action.

Useful safeguards include:

per-stage deadlines and bounded retries;
idempotency keys for state-changing external calls;
circuit breaking and concurrency limits around dependencies;
durable audit records at defined commit points; and
separate metrics for direct completion, fallback, retry, and recovery outcomes.

Measure the architecture, not just the aggregate

Average latency can hide both queueing and tail failures. Instrument each transition so the system can distinguish queue wait, execution time, persistence time, and downstream-service time. Then compare p50, p95, and p99 before and after the change under matched load.

For this workflow, the key measurement was not merely that a request became faster. It was that the old path spent substantial time waiting between otherwise short stages. That evidence justified changing the execution model. The percentile view then verifies whether the fast path improves typical and tail behavior, while fallback and error metrics show whether reliability has regressed.

Conclusion

The useful conclusion is not that functional programming delivers a fixed latency multiplier. The observed reduction from roughly 60 seconds to under 6 seconds came primarily from removing polling and queue wait from the common successful path.

Functional programming contributed by making the asynchronous orchestration, failure cases, and fallback boundary easier to express and review. The durable workflow system continued to matter for the work that needs decoupling, retries, and recovery.

Find the waiting first. Then choose an architecture that removes unnecessary waiting while preserving the operational guarantees the workload actually requires.