André Marinho - Posts

Designing agent skills around evidence and checks

Fri, 16 Oct 2026 00:00:00 GMT

A skill can contain correct advice and still produce an unhelpful review. The agent can apply a rule to the wrong surface, mistake a checklist for a standard, or report a passing result after inspecting only the source.

I built Engineering Skills around those failure modes. The collection covers documentation, technical SEO, search-facing content and web accessibility. The design problem was deciding which evidence each task needs and when the agent has enough of it to make a finding.

Split the work where the evidence changes

Technical SEO and content review share a goal, but their checks differ. A clear, well-supported article can send a noindex header. A correctly indexed page can contain an unsupported claim. Fixing either problem requires inspecting a different part of the system.

I separated these into technical-seo and search-content-review. The first follows a page from source through its response and rendered output. The second examines what the text asserts, the evidence supporting it, and the qualifications that must survive an excerpt. Neither skill claims to predict a search engine's private ranking system.

Documentation and accessibility get their own workflows for the same reason. Documentation needs comparison with the implementation: an omitted value and an explicit zero can have different behavior. Accessibility needs interaction evidence: a control with the expected name can still be impossible to operate by keyboard.

Each skill can be installed independently. Its main instructions and references stay inside its directory, so using the documentation skill does not depend on another skill being present.

Put decisions in the entry point

The technical SEO skill has this structure:

technical-seo/
  SKILL.md
  AGENT-DISCOVERY.md
  MEDIA.md
  SOURCES.md
  agents/openai.yaml

SKILL.md establishes the review scope, the evidence to collect and the required verification. Media checks and agent discovery have their own references. A whole-site audit must read both; a scoped fix reads the affected surface. That condition is explicit in the instructions.

This follows the Agent Skills format, which supports a main instruction file with additional resources loaded when needed. Splitting files alone does not decide when to read them. The entry point still has to say which task triggers which reference.

For example, a social image review needs to fetch and decode the image, check its crop and verify the actual metadata. Adding another generated card is unnecessary when an existing project image already works. The media reference carries those checks without putting them into every SEO task.

Record what a source can establish

Each skill has a SOURCES.md file with primary references, their status and scope, the date checked, and reasons to revisit them.

A W3C Recommendation, an informative tutorial and a community checklist have different authority. A checklist can reveal something worth investigating; the applicable standard and observed behavior determine whether it is a failure. The accessibility skill therefore asks the agent to check applicability and exceptions before attaching a WCAG criterion to a finding.

The distinction is concrete in its navigation checks. More than one way to locate a page can be provided by contextual links, search or a site map. The review has to inspect which paths actually reach the page. It cannot turn one example technique into a required route name. The accessibility source record also separates normative requirements from tutorials and draft specifications.

Search guidance has a similar boundary. An optional full-context file can help a tool read related material in one fetch. Whether that is useful depends on the task, publication scope and the consumer's limits. Its presence does not establish indexing or future citations. The agent discovery reference asks for that decision and the conditions behind it.

I kept the source records local to each skill so a separately installed skill retains the references needed to question its advice. When guidance changes, the instruction and affected source record need to change together.

Separate three kinds of validation

The repository has checks for its format and distribution. Review quality needs a different procedure.

Skill and manifest validation

scripts/check.py validates the portable plugin manifest against its schema, compares shared fields with the Claude-compatible manifest, invokes the Agent Skills reference validator for each skill, and runs Claude's strict plugin validators.

These checks catch malformed metadata, incompatible manifests and names that break the expected format. They do not verify every instruction, the truth of a source summary, or an agent's decision on a real task.

Packaging tests

scripts/test_package.py creates disposable copies and checks three paths:

The archive contains both manifests, the license and the skill files, with bytes matching the source. An unrelated .env file stays outside the ZIP.
A version change updates both manifests. Invalid versions and downgrades leave their contents unchanged.
Mismatched versions and symlinks are rejected without creating an archive.

The packager selects the two manifests, LICENSE and the skills/ tree. That keeps repository-only material outside the distribution, although files added inside skills/ still need review. It also writes to a temporary file beside the destination and replaces the final archive after writing it, avoiding a partially written final ZIP.

The build and these tests use Python's standard library. Schema and skill validation use the dependencies declared for that separate check.

Behavioral review

The contribution instructions require an independent agent to check a realistic task when a skill's decisions or dispatch description change. Evaluation artifacts stay in temporary workspaces. There is currently no committed behavioral suite to rerun across the four skills.

Applying the accessibility skill to this portfolio produced a useful example of why runtime checks matter. My animated headings wrap each word in an inline-block span with its own view-transition name. In Orca 46.1 with Chromium 149, line reading announced the title word by word, and a long title repeated part of its second line. A DOM inspection alone had not exposed that reading behavior.

The correction gives the heading one complete accessible label and hides its visual word spans from assistive technology. It keeps their view-transition names. This abbreviated example shows the semantic boundary:

import { Fragment } from "react";

<h1 aria-label={title}>
  {title.split(" ").map((word, index) => (
    <Fragment key={`${index}-${word}`}>
      {index > 0 && " "}
      <span
        aria-hidden="true"
        className="inline-block"
        style={{ viewTransitionName: `title-${id}-${index}` }}
      >
        {word}
      </span>
    </Fragment>
  ))}
</h1>

The implemented component supports multiple heading levels. Its regression test checks the heading and enclosing link's accessible names. That protects the DOM contract; the separate Orca recheck established the announcement behavior for the tested pages.

The review record documents speech-generation logs captured with a Speech Dispatcher dummy output module. I did not assess audible synthesis or test NVDA, JAWS or VoiceOver. This was a fix verified in one browser and screen-reader combination, without establishing WCAG conformance or a general success rate for the skill.

Keep publishing bounded

The release workflow reuses validation, synchronizes manifest versions, builds the ZIP, and publishes a GitHub release. It rejects an existing tag and checks main again before pushing the release commit and tag atomically.

That atomic push keeps the branch and tag update together. Creating the GitHub Release is a later API operation and can fail separately. The release guide explains how to rebuild from the existing tag and finish that step without bumping the version again.

The first release ZIP, published on October 15, predates the October 16 revisions described here. Directory submissions remain separate from the GitHub workflow, and a successful release says nothing about an official listing. The remaining maintenance work includes rechecking changed sources and exercising affected decisions when the instructions change.

A shared demo account without a reset scheduler

Thu, 15 Oct 2026 00:00:00 GMT

The demo in Turistar signs visitors into a real, shared account. They can move activities, edit a budget, and delete a trip through the same authenticated screens and operations I use for my own travel planning.

The next visitor needs useful examples even if an earlier visitor deleted them. I keep a saved baseline and request a restore when the demo account enters its dashboard, provided at least an hour has passed since the previous reset. There is no background scheduler.

You can open the login page and use its demo button. The account is shared, so changes are visible to other visitors and are temporary.

One account uses the normal product

The login and signup screens already have a demo entry point. Their sign-in helper authenticates the shared account through the application's auth flow. After login, the dashboard recognizes that account and calls resetDemoIfStale before fetching its data.

The demo feature documentation describes that path. A visitor uses the existing permissions, itinerary editor, and budget operations. I don't have a second implementation of those features to keep in step with the product.

The tradeoff is shared state. Two visitors can change the same itinerary or see each other's edits. Serializing the resets prevents two restore operations from competing; it does not give each visitor a private sandbox.

Entry requests a check; PostgreSQL decides whether to restore

The server helper makes one repository call, which invokes maybe_reset_demo. Calling the function on entry does not mean restoring the data on every entry. The database owns the interval check and records the last successful reset.

These statements from the restoration function show the synchronization point and the time rule:

select r.last_reset_at into last_reset
from public.demo_reset_state r where r.id = true for update;

if last_reset > now() - interval '1 hour' then
  return false;
end if;

The row lock holds competing resets behind the same bookkeeping row. Once the first restore completes, the next caller sees its updated timestamp and returns without repeating the work. The function also locks existing example snapshots in the same order as the itinerary writer, before restoring the plans.

For example, if the last reset ran at 10:00, an entry at 10:30 leaves the baseline untouched and an entry at 11:05 can restore it. With no later dashboard entry, no restore runs. The hour is a minimum interval since the last reset.

There is no dirty-check. After the interval expires, the function can restore the baseline even if no visitor changed it. Eligibility depends on the timestamp, without comparing the current data to the baseline.

Restore the relationships that make an example usable

Restoring just the itinerary JSON would leave several ways to break the demo. A deleted plan needs its original ID and public slug back so an existing URL works again. Its metadata, owner membership, expenses, and snapshot must agree with the restored trip.

The baseline therefore includes plan metadata, the itinerary snapshot, and budget entries. The reset recreates deleted examples, replaces edited example data, restores membership, clears their old event history, and removes extra plans created under the demo account. It also restores the demo profile. A baseline plan that now belongs to a different account causes the function to fail rather than take ownership of that plan.

Dates need maintenance too. Rome starts yesterday and Boipeba starts in 30 days, relative to America/Bahia. The restore shifts both plan dates and itinerary day labels while preserving activity IDs and content. A prepared trip stays useful for exploring ongoing and upcoming travel without someone periodically editing its calendar.

Protect the baseline from the account it repairs

The demo account can edit product data, but it cannot edit the saved baseline or reset bookkeeping. Those tables have Row-Level Security enabled, and direct privileges are revoked from visitor roles.

The restore is a security definer function with an empty search_path and qualified table names. It checks the caller inside the function: the demo identity can restore itself, and the defined database maintenance roles can run it during setup. Another authenticated account cannot trigger a demo reset merely by calling the RPC.

A visitor with write access to maintenance data could replace the examples or move the timestamp that decides when they return.

The dashboard stays available when reset fails

The server helper catches reset failures, allowing the dashboard to continue loading. Restoration is best-effort. An already-open tab is not refreshed automatically, and a failed reset can leave the examples altered until a later entry succeeds.

The integration tests exercise restoration against a local database, including deleted examples and their URLs, date shifting, access boundaries, and repeated or concurrent reset calls.

Keeping drag-and-drop stable during realtime updates

Sun, 04 Oct 2026 00:00:00 GMT

A card moving under the pointer can change position many times before someone drops it. In Turistar, those intermediate positions need to look immediate without becoming a sequence of persisted itinerary changes. Remote updates make the problem harder: another screen can change the same plan while the gesture is active.

The January implementation kept a local draft for the drag and saved the final result once on drop. In an August simulation using that revision's drag code, a path across a full column and into the next on a four-day board with four activities per day produced seven effective reorder steps. Publishing every step would mean seven writes; committing the result meant one.

That design also exposed a stale-draft problem. In September I changed the commit boundary again, from submitting the whole itinerary draft to submitting the moved activity's ID and intended destination.

The original drag draft belonged to the board

In the January board component, draftDays supplied the rendered columns. The drag hook received setDraftDays for preview changes and a separate callback for the final commit.

handleDragOver updated only the draft. Its requestAnimationFrame scheduling retained the latest hovered target while allowing at most one pending frame callback. That reduced redundant local work without sending an update to the persistence layer on each pointer event.

The drop handler resolved the final target, applied any remaining local move, and called onDaysCommit if a local reorder had occurred. Cancellation cleared the drag state without publishing that draft.

Freezing the draft kept remote state out of the gesture

The board copied incoming shared state into its draft only when no activity was being dragged:

useEffect(() => {
  if (!activeId) setDraftDays(days);
}, [activeId, days]);

Remote events could update the shared days while the visible draft stayed stable. A remote reorder would therefore not move the dragged card underneath the pointer midway through the gesture. Once the drag ended, the board could synchronize with shared state again.

A debounce on persistence alone would not provide that behavior. It could delay writes while still letting remote state replace the array that the active gesture was rendering. The draft gave the board a separate state boundary for the duration of the interaction.

The measured path had seven steps, not every drag

The simulation used the real applyDragMove function and counted the steps that returned a changed order. The scenario was four days with four activities per day, moving across a full column and into the next.

Seven changed intermediate orders could have triggered seven persistence calls if every preview had used the shared-state setter. The local-draft path published one final result. A short drag has fewer intermediate changes, and an unchanged or cancelled drag may publish none. Seven-to-one describes this modeled path.

This was a code-level simulation, without captured user traffic or a latency measurement.

A whole draft can accidentally describe a deletion

The January revision eventually committed the final DayPlan[]. The collaboration layer compared that array against its current shared state to produce events.

Suppose a second screen added an activity while the first screen was dragging. The shared state could receive the addition, while the frozen draft never contained it. On drop, comparing the current shared state with that old draft could interpret the missing activity as an intentional deletion. A concurrent edit to an existing card could similarly be overwritten by the draft's older fields.

The gesture remained visually stable while the eventual commit could still misrepresent what the person intended. Versioning the resulting events did not recover the intent lost in that whole-array comparison.

That conflict required edits to the same itinerary during the active drag and its commit. I did not measure the race window or its frequency. This limitation belongs to the linked historical revision; the later move contract avoids submitting that whole draft.

The later commit describes a move

The September change removed that whole-draft commit path. The hook retains the active activity and destination, using moveActivityOperation to project a preview over the latest days. On drop it calls the move callback with an activity ID and an ID-based destination:

onActivityMove(activityId, {
  toDayId,
  beforeActivityId,
});

This shows the callback contract; the implementation resolves those values from the hovered destination. The operation asks to move one activity before another, or to the end of a day. It does not ask to replace every activity with a local copy.

A regression test starts a drag, supplies updated remote days, and checks that a remote title survives in the preview. It also checks that drop publishes the activity ID and destination, and that cancellation publishes no mutation. The operation helper returns no move for a missing activity or destination.

The new boundary avoids expressing unrelated remote additions as deletions merely because a drag preview omitted them. Concurrent moves of the same activity still require an ordering policy, and this event-sourced design does not promise CRDT conflict resolution.

The partial unique index that broke my Supabase upsert

Thu, 01 Oct 2026 00:00:00 GMT

Opening the notification panel in LawFlow recalculated reminders from leads, proposals and activities. The calculations could produce notifications that already existed. My repository tried each insert and swallowed PostgreSQL's 23505 unique-violation error to keep the list deduplicated.

That preserved uniqueness, but an ordinary panel opening could produce dozens of failed inserts. I changed the service to collect candidate rows and write them in one batch. Then the batch failed: PostgreSQL could not find a matching unique constraint for the conflict target.

What the duplicate meant

Each notification had a deduplication key identifying the reason it existed, such as a particular reminder for a particular activity. Uniqueness applied to the combination of workspace, recipient and deduplication key. The same event could notify several people without colliding across recipients or workspaces.

The existing index had this shape:

CREATE UNIQUE INDEX idx_notifications_dedupe_per_user
  ON notifications (workspace_id, user_id, dedupe_key)
  WHERE dedupe_key IS NOT NULL;

The service's five calculation functions previously wrote rows themselves. I made them synchronous functions that returned candidates, kept the database reads in the orchestration step, and passed the combined rows to one repository method. An empty batch returned immediately.

The write used Supabase's upsert API:

const { error } = await db.from("notifications").upsert(payload, {
  onConflict: "workspace_id,user_id,dedupe_key",
  ignoreDuplicates: true,
});

if (error) throw new Error(error.message);

ignoreDuplicates: true matters here. The intended conflict action was DO NOTHING. Recomputing an existing notification should preserve its read status and original timestamp. Updating it from the new payload, which contains read: false, could make a notification unread again. Supabase's upsert reference describes the conflict columns and the choice controlled by ignoreDuplicates.

Matching columns did not identify the partial index

PostgreSQL infers an arbiter index from the ON CONFLICT target. A partial index also needs a compatible predicate in that target. The column list alone did not identify this partial index, even though the attempted row had a non-null deduplication key. PostgreSQL documents this distinction in its conflict-target rules.

In direct SQL, that target could include WHERE dedupe_key IS NOT NULL. The Supabase upsert API I was using exposed the conflict columns, without an option for the index predicate.

The table definition made the correction simpler. dedupe_key was already NOT NULL. So were workspace_id and user_id. Every valid row satisfied the index predicate; it selected no smaller subset of the table.

I replaced the partial index with a non-partial unique index on the same columns:

CREATE UNIQUE INDEX idx_notifications_dedupe_per_user
  ON notifications (workspace_id, user_id, dedupe_key);

These snippets show the before and after definitions, not a migration to run together. The replacement retained uniqueness for every valid row and gave the column-only conflict target a matching index.

The NOT NULL constraint is important to that reasoning. A normal PostgreSQL unique index permits multiple nulls by default; replacing a partial index does not automatically make nulls equal. That is a separate unique-index rule. Here, the schema excluded nulls before either index was considered.

Why I kept deduplication in the database

Fetching existing keys first would let the service omit known duplicates, but two requests could both read an absent key before either inserted it. An in-memory set would only coordinate one request. Two browser tabs could still generate the same notification concurrently.

The unique index remained the authority. DO NOTHING handled an expected collision at the write boundary, and unrelated database errors still propagated. The batch removed the per-candidate network calls without weakening the protection against concurrent requests.

Repository tests checked the batch payload, conflict options, timestamp mapping and empty-input behavior. Service tests checked which candidates the rules generated. Those tests helped keep the refactor faithful to the existing notification behavior; mocked repository tests alone would not have exposed the index-inference failure.

Fewer statements and a smaller latency improvement

In an isolated workspace seeded for the comparison, a recomputation produced roughly 30 to 60 candidates. The write path went from that many individual insert statements to one batch statement. Candidate reads and the final inbox query still existed, and the database still checked each proposed row for conflicts.

Elapsed time improved by roughly 20% to 40% in that scenario. The old inserts already ran concurrently through Promise.all, so replacing them did not save 30 to 60 sequential round trips. The larger reduction was in statement count and expected-error handling. A smaller workspace would generate fewer candidates and show a smaller absolute reduction.

Recomputation also remained on the request path whenever the list included unread notifications. Batching changed how candidates were persisted; it did not turn notification generation into a background process.

Fetching dashboard summaries instead of full snapshots

Sat, 26 Sep 2026 00:00:00 GMT

The Turistar dashboard shows trip cards and a map of destinations. It needs dates, coordinates, a cover image, and an activity count. It was also fetching the itinerary snapshot for each destination so the application could count those activities.

I replaced that path with one database call returning dashboard summaries. In a controlled benchmark with 50 plans containing 40 activities each and 30 ms of added database API latency, median data-loading time fell from 129.10 ms to 39.03 ms, a reduction of 69.77%. Those timings measure HTTP request to parsed JSON, not full-page rendering.

The change shipped in PR #518. The dashboard receives the values it displays, while PostgreSQL reads the snapshots needed to calculate them.

One screen was loading through several paths

Before the change, the page loaded plans and destinations through separate paths, including a snapshot read per destination. An itinerary snapshot contains the days and activity records used by the planner. Most of those fields have no use in a dashboard summary.

The application still had to receive and parse that content to derive a count. The per-destination snapshot reads already ran through Promise.all. They were parallel, but each still crossed the database API boundary and transferred the snapshot content.

I introduced get_user_plan_summaries, a query dedicated to this screen, and changed the page to call PlanService.getUserDashboard(). The service receives summary rows once and derives both the trip cards and map destinations from them.

Count inside the query, return the summary

The SQL function first collects the plan IDs the caller owns or belongs to. It uses UNION, so a plan present through both relationships appears once. It joins those plans to their stored snapshots and calculates the count in SQL.

This is the activity-count expression from the function:

coalesce((
  select sum(case when jsonb_typeof(day->'activities') = 'array'
    then jsonb_array_length(day->'activities') else 0 end)
  from jsonb_array_elements(case when jsonb_typeof(ps.state->'days') = 'array'
    then ps.state->'days' else '[]'::jsonb end) as day
), 0)::bigint

The JSON type checks give missing or non-array day and activity collections a defined count behavior. A missing snapshot is still allowed by the left join and yields a zero count. The application receives activity_count alongside the plan's display fields; it no longer needs state to reproduce the traversal.

This is a query over the existing data, without a separate summary table or background synchronization job. PostgreSQL still traverses the relevant JSON to count activities. One RPC reduces request overhead and transferred content; it does not make query work independent of the amount of itinerary data.

Keep authorization and display limits explicit

The RPC is security invoker, so it executes under the caller's database permissions and Row-Level Security policies. Execution is granted to authenticated accounts and revoked from anonymous access. The summary query keeps authorization at the data boundary while selecting owned and shared plans.

Cards and the map have different limits. At this revision, the dashboard displayed the latest 50 plan cards, but the map needed the complete destination history. Putting LIMIT 50 in the shared query would quietly remove destinations from the map.

The service therefore limits only the cards. It maps all summary rows with a destination into map entries. A plan without a destination can still have a card without producing a blank map location. The previous RPC remained available during rollout so older application instances could continue using it.

What the timing establishes

The controlled comparison uses the same 50-plan, 40-activity workload and 30 ms added API latency for both paths. Reducing median time from 129.10 ms to 39.03 ms gives:

(129.10 - 39.03) / 129.10 = 69.77%

I also observed a reduction of about 70% in dashboard data loading in production. I have not retained the absolute production timings, traces, or sampling protocol, so the two precise millisecond values above belong only to the controlled benchmark. Neither observation establishes an equivalent improvement in LCP, login time, or complete page rendering.

The benchmark includes database API latency, which makes avoiding per-destination calls relevant to this workload. A smaller plan history or a different network environment can produce a different reduction.

Check that less data still produces the same screen

The repository tests check the summary RPC call and error handling. The service tests use 55 rows to assert that only 50 become cards while all 55 remain available to the map. They also cover empty data, destination-less plans, zero coordinates, dates, authentication, and propagation of failures.

Those checks constrain the optimization to the dashboard's existing contract. A response can become smaller and faster while accidentally losing a shared plan or truncating the travel history; the read model needs to preserve those behaviors as explicitly as it removes the full snapshots.

Removing the login-to-dashboard waterfall in Next.js

Tue, 11 Aug 2026 00:00:00 GMT

The slow part of entering LawFlow crossed several systems. After authentication, the browser hydrated its session, resolved the workspace, checked billing access, loaded shared workspace data and finally mounted screens that could request their own data.

The user had to wait for a chain of dependent browser requests. Optimizing a query helped its own stage while leaving the rest of that chain intact.

I changed the authenticated entry route to resolve an authorized bootstrap on the server and pass the result into the client providers. The browser could initialize from that snapshot instead of discovering the workspace and rebuilding the shared state after mounting.

Following the dependencies across providers

The loading path had grown as authentication, multi-tenancy and billing were added. Session polling delayed workspace resolution. A billing gate controlled whether parts of the application mounted, so their data requests started only after that gate finished. Other paths repeated workspace or authorization lookups through separate calls.

My first changes stayed within that structure. I replaced session polling with explicit session hydration, let independent billing and bootstrap work run in parallel, and made a detailed subscription-status request conditional on denied access. A user already allowed by the entitlement check did not need that extra request before entering.

The intermediate flow still took approximately 5.7 to 6 seconds in production. The request map at that stage contained about ten authentication or database operations on the successful path, even though some were parallel or shared an HTTP batch. Counting HTTP requests alone hid work performed inside each request.

The remaining question was which information the browser actually needed to discover for itself. The server already knew the authenticated user before rendering the entry page. Resolving the same user's workspace after that page mounted added another dependency boundary.

One entry route produces the initial state

The authenticated page now follows this shape:

const session = await getServerSession();
if (!session) redirect("/login");

const initialBootstrap = await resolveCrmShellData(session);

return <CrmView initialBootstrap={initialBootstrap} />;

The resolver verifies the workspace for that authenticated user, reads the workspace context needed by billing, resolves access and then loads the authorized bootstrap data. Reusing the workspace row avoids fetching it again inside billing.

The snapshot contains shared application state: the current user's profile, workspace members, office settings, field configuration, notification settings and onboarding status. Client providers initialize their state from those values. Their mount no longer starts a second bootstrap through useEffect.

Screen-specific queries still exist. Moving the bootstrap did not require loading every lead, proposal or dashboard result before returning the page. The boundary covers the shared state required to enter the CRM.

Next.js supports passing serializable data from Server Components into Client Components through props. That is the server/client boundary used here. A prop reaches the client, so the bootstrap has an explicit shape rather than passing through an unrestricted database result.

Access checks determine which snapshot can exist

Moving work to the server also made the authorization order explicit. The resolver derives the workspace from the verified caller; it does not trust a workspace selected in the browser. It loads application bootstrap data only after billing permits access.

Denied access produces a recovery snapshot with the information needed to show the billing gate. Failure to check billing produces an unavailable state with a retry path. Neither branch falls through to an authorized CRM with empty defaults. A missing workspace is handled as a workspace error rather than being relabeled as a billing outage.

API operations retain their own authorization checks. The snapshot reflects authorization for that render; it is not permission for later mutations. Removing repeated checks within that render did not remove the checks at the API boundary.

The login action needed attention too. After it wrote the session cookies, the client refreshed its router state and navigated to /. That entry request produced the bootstrap against the fresh session. Returning success from the action avoided rendering the same bootstrap inside a server-action redirect and then doing it again during navigation.

The original path took approximately 7,441 milliseconds from clicking Log in to the rendered CRM. After the server bootstrap changes, measurements during the implementation were approximately 760 milliseconds for that same full flow, about a 90% reduction.

These are approximate end-to-end measurements from the implementation. I did not preserve the final raw traces or a reproducible set of runs. The intermediate production measurements and request map were recorded, but the final numbers should not be read as a controlled benchmark or a latency guarantee for every workspace and network condition.

Tests covered the resolver's authorized, denied and unavailable branches, snapshot mapping and login-action failures.

Server-side loading still has a critical path. Authentication must precede workspace resolution, and access must precede loading protected application data. The improvement came from placing those dependencies in one server-owned flow, reusing resolved context and letting the client begin with the result.

When the event version was current but the snapshot wasn't

Tue, 28 Jul 2026 00:00:00 GMT

While investigating stored itinerary data in Turistar with SQL, I found that the snapshot content did not match the event history. The snapshot version could advance successfully while its itinerary stayed old or empty.

Appending the events advanced their version. Updating the snapshot content required an optional argument that the caller wasn't sending. The database accepted the append and recorded the new version, leaving readers with a misleading checkpoint.

The investigation led to a server-side snapshot builder, shipped in the January 2026 change. It applies the events before persistence and sends the calculated state in the same database call as the event batch.

What a snapshot version is supposed to mean

Turistar transports itinerary changes as events such as activity.created, activity.moved, and day.reordered. Each accepted event receives a monotonically increasing version within its plan. Other clients apply those events through the shared reducer.

A snapshot lets a reader start from a materialized itinerary instead of rebuilding the plan from its first event. For that to work, the snapshot's version must describe the events already reflected in its content:

snapshot at version v + events v+1 through n = itinerary at version n

If the snapshot claims version n but still contains the itinerary from an earlier version, a client requesting only events after n cannot recover the missing changes. Comparing version numbers will not expose the missing content because the stored number itself is current.

The caller omitted the content argument

The repository before the fix called append_plan_events with plan_id, base_version, and events. It did not include snapshot_state.

The SQL function accepted that omission: snapshot_state defaulted to NULL. After inserting the events, the update used this expression:

UPDATE plan_snapshots
SET version = new_version,
    state = COALESCE(snapshot_state, plan_snapshots.state),
    updated_at = NOW()
WHERE plan_snapshots.plan_id = append_plan_events.plan_id;

With no new state supplied, COALESCE deliberately retained the previous state while the version advanced. When the function had to insert a missing snapshot, the equivalent fallback was {"days":[]}.

The event append and snapshot update could run together successfully and still produce an invalid checkpoint. Transactional execution could not compensate for the caller supplying events without their corresponding materialized state.

Build the next state before appending

The corrected server append flow fetches the current snapshot, passes it and the incoming events to buildSnapshotStateForAppend, then supplies the resulting snapshot_state to the repository.

For a snapshot whose version matches baseVersion, the builder assigns the incoming events consecutive versions beginning at baseVersion + 1. It applies them with the same reducer used to interpret the event history and serializes the resulting days as JSON-safe state.

The database still checks base_version under its snapshot row lock. If another append wins between the server's read and its write, the database sees the version mismatch and returns the current version without inserting that batch. Calculating a snapshot on the server does not replace the database's concurrency check.

When the versions match and the server supplies the calculated state, the RPC writes events and their resulting snapshot together. The client does not need to follow a successful append with a separate snapshot update that could fail independently.

Recover a known empty-snapshot failure

An empty snapshot with a nonzero version is a specific sign that this recovery path can investigate. The server fetches the plan's history from version zero, and the snapshot builder checks that the history's highest version equals the requested base version before rebuilding.

It replays that history onto empty days at version zero, then applies the incoming batch. This lets a later append reconstruct an empty materialization from the retained log, rather than treating the empty days as the correct starting point.

There are limits to that recovery. The builder does not inspect every nonempty snapshot for incorrect content, and checking the highest history version is not a proof that every expected event is present. Returning null from the builder also does not itself reject an append: the caller can still invoke the RPC without a replacement state. The fix addresses the normal state-building path and the identified empty-snapshot case; it is not a general audit of every stored checkpoint.

Test state as well as versions

The builder tests added with the change check version mismatch, empty input, missing recovery history, and the resulting activity content for a valid append. An assertion that the version increased would have missed the original problem.

I have not retained the exact SQL queries used during the investigation or a count of affected people. The repository history preserves the omitted argument, the SQL fallback, and the state-building change.

Why my Postgres pagination cursor needs a timestamp and an ID

Thu, 23 Jul 2026 00:00:00 GMT

The read-notification history in LawFlow used offset pagination. The interface only needed to load older notifications, but the query described its position as a number of rows to skip. Each deeper request asked PostgreSQL to compute and discard a larger prefix of the result.

I replaced the offset with a cursor containing sent_at and id. The timestamp located the boundary in the history; the ID made that boundary unambiguous when several notifications shared a timestamp.

A timestamp does not completely order the inbox

Notifications can share sent_at, including several generated in the same batch. Ordering only by that field leaves their relative order unspecified.

Suppose a page ends partway through a group with the same timestamp. A next-page predicate of sent_at < lastTimestamp skips the rest of that group. Changing it to <= can return rows already displayed. Increasing the timestamp's precision would still leave correctness dependent on timestamps being unique.

The query therefore orders by both fields:

ORDER BY sent_at DESC, id DESC

The primary-key ID supplies a unique tie-breaker. It does not need to encode creation time because sent_at provides the chronological order. The same two fields must appear in the cursor and in the continuation condition.

Continue strictly after the last returned row

A shortened SQL equivalent of the paginated query is:

SELECT id, sent_at, title
FROM notifications
WHERE workspace_id = $1
  AND user_id = $2
  AND read = true
  AND (
    sent_at < $3
    OR (sent_at = $3 AND id < $4)
  )
ORDER BY sent_at DESC, id DESC
LIMIT $5;

Here $3 and $4 are the last displayed row's timestamp and ID; $5 is the requested page size plus one. The first page omits the cursor predicate. Workspace, recipient and read-status filters remain on every request. A cursor identifies a position within that authorized query; it grants no access by itself.

Because the order is descending, older timestamps come after the boundary. At the same timestamp, smaller IDs come after it. Using < on both branches keeps the boundary exclusive. Changing the sort direction would require changing these comparisons too.

The Supabase repository expresses the same condition through .or():

query.or(
  `sent_at.lt.${cursor.sentAt},and(sent_at.eq.${cursor.sentAt},id.lt.${cursor.id})`,
);

The API validates the cursor as a timestamp and UUID before it reaches that filter. The client takes the next cursor from the last row actually displayed, preserving the timestamp value returned by the server.

One extra row answers the UI's question

For a requested page size of 20, the repository asks for at most 21 rows. It returns the first 20 and sets hasMore when the result contained the extra row. The client continues from row 20. Using row 21 as the cursor would skip a notification that had never been displayed.

An empty result ends the traversal. A result with exactly 20 rows and no extra row also has hasMore: false. This answers whether another page existed when the query ran, without requesting an exact total just to draw a Load more control.

The interface gives up direct jumps to an arbitrary page number. That fits an inbox where the action is to read further back. A numbered reporting table could require a different tradeoff.

The indexes still determine how much work remains

PostgreSQL's LIMIT and OFFSET documentation explains both requirements behind the change: pagination needs a predictable order, and skipped offset rows still require work on the server. Adding an index to an offset query does not remove that skipped prefix.

The cursor migration added a B-tree index on (sent_at DESC, id DESC). The schema already had another index on (workspace_id, user_id, sent_at DESC). Those are different access paths. The first matches the complete ordering but does not begin with the tenant and recipient filters. The second begins with those filters but does not contain the ID tie-breaker or the read-status filter.

Neither index covers all the filters and the complete ordering. PostgreSQL still chooses a plan and may filter rows or sort. The index-ordering rules explain when a B-tree can supply ordered results directly. Tenant distribution, read-status selectivity and timestamp ties still matter.

I compared the offset and cursor versions with EXPLAIN ANALYZE, checking the first and fiftieth pages against a seeded history of roughly 50,000 notifications. This was preventive work: the product's actual volume did not show a noticeable user-facing difference. The comparison supported removing offset-driven degradation in that scenario; it did not establish constant latency for every dataset.

Stable boundaries do not freeze the history

Newer notifications can arrive above the current boundary without shifting the cursor's position as they would shift an offset. That does not give the traversal a database snapshot across requests. Deletions, notifications moving between read and unread, or changes to ordering fields can still change what later pages contain.

The client refreshes read history from the first page when it needs a fresh view and merges loaded notifications by ID. The composite cursor solves the ordering and continuation problem for that flow. It does not promise a permanent, unchanged enumeration of a live inbox.

Hello World

Fri, 17 Jul 2026 00:00:00 GMT

console.log("Hello, world");

The site has been up for a while. The blog has not, mostly because I kept deciding I had nothing finished enough to write about.

This runs on Next.js, TypeScript and Tailwind. Posts are markdown files in a folder, which is enough for this small blog. I would rather add a CMS or database when maintaining the files becomes a problem. Everything renders to static HTML at build time.

I wrote it from scratch instead of starting from a template, which cost me a weekend I could have skipped. Worth it anyway. A portfolio claiming I write software should be software I wrote.

Some context on who is typing

I ran Duonorth from 2017 to 2025. It began as a business intelligence consultancy, expanded into digital strategy and marketing around 2020, and focused on websites and software from 2023. In July 2025, software product development became my main occupation.

Current projects include Turistar, an open-source planner for my own trips; create-mvp, a CLI on npm for the project setup I got tired of assembling by hand; and client work in production.

Each project leaves me with decisions I want to revisit. Some are wrong, and I would like them written down somewhere they can be argued with.

What goes here

I want to write about things I built and how they broke, including choices I later undid and the bug that ate an afternoon when it should have taken ten minutes. Some of those will only need a short note.

Two are up already: what changes when AI writes most of your code, and the work that led me here.

Code for this site is on GitHub. If I got something wrong, tell me.

Learning While AI Writes the Code

Sun, 21 Jun 2026 00:00:00 GMT

It works and I don't know why.

That is the most dangerous sentence I can say about my own code, and it got very easy to say. By the time software product development became my main focus in July 2025, I had already spent years building automations and websites. Now I use AI while going deeper into TypeScript, databases, authentication and automated tests.

When I encounter something unfamiliar, a tool can generate a working solution before I understand why it works. It is tempting to accept the code and move on: the interface works, the tests pass, and the gap stays out of sight.

I use AI every day, and I would be slower and poorer without it. What I want to understand is how much I learn when the machine hands me working code, and how much I simply collect.

The failure that teaches, and the one that doesn't

Broken code fails loudly. You get a stack trace, a red test, a page that will not load. You fix it, and in fixing it you learn where you were wrong. That was the old deal: the bug was the tuition.

The deal is still on offer, but the window is much shorter. Paste the error back, the fix comes down, the page loads, and you can be past it in forty seconds without ever having formed a theory of what went wrong. The failure still happens. Whether it teaches anything now depends entirely on whether you stopped to look, and there is a great deal of pressure not to stop.

Working code I do not understand can leave that gap hidden until a requirement changes or an edge case shows up in production. Sometimes someone asks why I built it that way, and all I can say is that a model suggested it and the tests were green.

The place this scares me most is multi-tenancy. A mistake in an access policy can expose one account’s data to another while the application appears to work normally. A passing test suite only helps if it checks that boundary. I need to understand what the policy allows and test who can access each record.

I had seen this before, in marketing

When Duonorth expanded into marketing around 2020, I saw a similar problem with campaign strategies.

Someone would find a competitor's funnel and copy it. Same offer structure, same ad angles, same email sequence, same landing page. Sometimes it worked for a while, which was the worst possible outcome, because it confirmed the method.

Then something moved. The traffic source got more expensive, the audience shifted, the competitor dropped their price. And there was nothing to do, because there was no model of why any of it had been built that way in the first place. You cannot adjust a strategy you do not have. You can only go copy a newer one.

AI-generated code can leave me in the same position, even when it draws on more codebases than I will read in my life. I still need to understand why this approach fits before I can adapt it to a change.

What understanding buys you, concretely

Every problem I actually sat with turns into a better instruction the next time. The first version of a feature gets described as what I want. The second version gets described as what I want, minus the four things I now know go wrong. That second description is worth more than the code that came out of the first one, and it is not something a model can hand me. It is the residue of having watched something break and bothered to find out why.

There is a second thing, harder to justify on a timesheet. When the mechanical part is handled, there is room to be curious about the domain instead of the syntax. I have read more about how Postgres actually evaluates a policy, or what a queue guarantees and does not, than I would have if I had been heads-down fighting the language. I have to choose to spend that time investigating.

What I actually do about it

These are the habits I use to catch myself accepting code before I understand it.

Ask for the reasoning before the code. What were the alternatives, and why this one. I read that first. If the answer comes back generic, the code is usually generic too, and that is a signal about the prompt more than the model.
Explain it out loud before merging. I do this even when I am alone. If I cannot say what a block does and what would break without it, I need to read it more carefully.
Delete and rewrite the parts I will have to live with. For the core of a feature, I close the suggestion and write it again from memory. It is slow, so I reserve it for code I know I will come back to. If I cannot reproduce it, I need to work through it again.
Write down why. create-mvp has 35 architecture decision records in it. Explaining why I chose one approach over another makes it obvious when I cannot justify a decision yet. The decision records are public.
Break it on purpose. Change a value, remove a guard, delete a line, and watch what fails. If nothing fails, either the code does nothing or the tests do not cover it, and both of those are worth finding out on a Tuesday instead of in production.

What I still don't know

The concern I cannot dismiss is that iterating faster means encountering more problems per hour and understanding each one less. I have opinions about a lot of things I have only met once, through a failure that got fixed quickly, and I cannot always tell which of those I know and which I merely recognize.

Questions I cannot answer about code that is already running show me where I need to spend more time. I have collected a few of those.

AI is very good at the fifth CRUD form, at wiring I have already wired four times, at the boilerplate that teaches nothing on the sixth repetition. It is better than any tutorial I have found at explaining unfamiliar code, which turns out to be most of the job. It helps me move faster, which makes it more important to keep track of the decisions I can explain and the ones I still need to study.

I wrote about how my earlier work led me here, and about why this site exists. If you think I have this wrong, I would like to hear it.

I Was Building Software Before I Called It Code

Tue, 17 Feb 2026 00:00:00 GMT

In 2014 I worked in the finance department at Grupo Hemocat, a medical device distributor in Salvador. The finance manager updated a planning spreadsheet by hand, copying information from a printed system report almost every day.

I asked her if I could try to automate it. That became my first technical project: learning how the system's database worked and connecting Excel directly to the local SQL database.

In July 2025, software development became my main occupation. A lot of the work that led me there happened in finance, logistics and business consulting.

Connecting the spreadsheet to its source

The spreadsheet already existed. The task was to let it read from the system instead of depending on someone to copy the figures across.

That changed what a discrepancy meant. If a value was wrong in the spreadsheet, we could trace it back to the source instead of wondering whether it had been mistyped during the update.

It did not remove the need to check the numbers. Errors in the system still needed someone to investigate them. What it removed was the repeated work of extracting and transferring the information.

I was learning about databases by working with one that people already depended on.

Then came logistics

In 2015 I became logistics supervisor at the same company, working with inventory, distribution, purchasing and imports.

I modelled stock availability and built a Power BI dashboard to support purchasing and distribution decisions. A unit in stock is not one thing. It can be available, committed, in transit, in customs or on consignment. Treating all of those as the same number is how you promise a hospital something you cannot deliver.

The model had to reflect those differences so that purchasing, sales and logistics could work from the same view. Getting the data onto a screen was only part of the job; deciding what it represented mattered just as much.

How Duonorth changed

In 2017 I started Duonorth Studio as a business intelligence and business solutions consultancy. I worked with clients to understand their operations, reconcile data and build dashboards, spreadsheets and automations they could use in their daily work.

Around 2020, Duonorth expanded into marketing and digital delivery. The work connected business analysis with campaigns, websites, landing pages and software. I handled diagnosis, scope and the relationship with the client, bringing in specialists as the work grew.

From 2023, I concentrated the business on websites and software. I was both directing the work and implementing it: WordPress sites, themes, plugins, interfaces and integrations in HTML, CSS, JavaScript and PHP.

In July 2025, software product development became my main occupation.

What carried over

I still ask where the data lives before designing anything on top of it, and what someone needs when they bring me a requirement. Knowing what they will do with the answer helps me design the interface. I also draw on the experience of agreeing on a scope with a client and following it through delivery.

What I'm still learning

The current work takes me deeper into relational databases, authentication, security, automated tests and continuous delivery. Earlier experience with dashboards and websites helps, but it does not answer every question that comes up in a software product.

That experience helps me frame the problem. I still have to test my assumptions about the systems I build and learn from what breaks.

I wrote more about the learning part in working with AI without skipping the understanding. The current work is on GitHub.