Skip to content

The AI fluency trail guide

AI fluency is not prompt polish. It is the habit of moving work out of one long, fragile chat and into artifacts a machine can read, check, resume, and audit.

This project is a board-game app, but the useful lesson is the build loop around it. The current repository has more than 1,800 ticket run records on disk. The local history index reports 1,801 accepted runs (merged or shipped-with-escalation) and 1,832 run records total. I am using those counts, not the old pull-request table from an earlier draft, because the local PR cache is empty in this clone and I cannot re-verify those PR numbers here.

The trail below is the path from "I asked a chatbot" to "the project has a ticket engine, review gates, history queries, and an in-progress Go port named Tempo." It is not a maturity badge. Each stage names a concrete capability, the failure mode that appears next, and the project artifact that replaced a manual habit.

Stage 1 -- Ask

At first, AI is a better search box. You ask it questions in normal language instead of trying search keywords. That is useful, but it is still passive: the model answers and you decide what to do.

The first shift is to give it a job. Instead of "What is the syntax for X?", you say "Given this file and this goal, change X without touching Y." That sounds small, but it changes the interface from lookup to delegation.

The failure mode is obvious: the model gives a confident answer that is wrong. The fix is not blind trust. The fix is better task framing and evidence.

Stage 2 -- Control Context

The next lesson is that context is a budget, not a diary.

Long chats feel convenient because they remember everything. They also collect stale assumptions, half-resolved decisions, and old code. Eventually the model starts optimizing against yesterday's conversation instead of today's task.

This project's answer is the ticket. A ticket is a small context packet: goal, scope, files to read, acceptance criteria, verification commands, and the machine-readable ## Touches surface. The ticket that produced this post even had a ## Context section listing the files to read before editing. That is the pattern: do not hope the agent finds the right context; put the context boundary in the work item.

The plateau is hand-writing every task from scratch. You can delegate a single task, but you are still the scheduler, reviewer, and memory.

Stage 3 -- Write Down The Rules

Once an AI can act, the next problem is repeat mistakes.

This repo has standing agent rules in CLAUDE.md and AGENTS.md. They are not style preferences. They are scars from failures that were expensive enough to prevent. "Never hunt the filesystem for executables" exists because using a random system binary makes verification meaningless. "Author every ticket you identify in the same turn" exists because noticed follow-ups disappear if they stay in prose. "Propose the class-level prevention" exists because fixing one instance and leaving the class open just schedules the next failure.

The important move is not having many rules. The important move is treating a rule as a durable patch to the process. If a failure recurs, the question is not "how do I remind the agent harder?" It is "where should this become impossible or at least mechanically visible?"

The plateau is a rulebook that still depends on a person to run the sequence.

Stage 4 -- Turn Work Into Contracts

The project stops being one prompt at a time when work becomes schedulable.

A backlog ticket carries state, priority, agent_tier, agent_effort, agent_context, authoring_mode, predictions, dependencies, and verification commands. ## Depends on lets the orchestrator order work. ## Touches lets it avoid obvious collisions. The ticket is not just instructions for a model; it is input to a scheduler.

That is the difference between a prompt and a contract. A prompt asks an agent to try. A contract gives the system enough structure to launch, route, check, and later diagnose the attempt.

The plateau is that multi-step work still fails opaquely. If a run stalls or ships bad work, you need to know which part failed: task spec, environment, implementation, review, merge, or cleanup.

Stage 5 -- Put Gates Between Agents

This is where "AI-assisted" turns into engineering.

The current review configuration lists hard checks such as lint-ascii, lint-devblog-mirror, lint-doc-tags, lint-run-records, lint-test-marks, lint-no-direct-random, lint-coverage, test, tempo-check, and docs-build-strict. It also has diff-scoped checks, client-only checks, and soft checks that self-report drift without blocking an unrelated merge.

The point is not that every gate is clever. Most gates are boring, and that is why they work. Closed vocabularies catch invented tags. ASCII lint catches characters that break shell and parser paths. The devblog mirror lint catches a missing same-slug technical summary. Run-record lint catches malformed audit artifacts. None of those jobs needs a model.

Use the model where judgment matters. Use deterministic code where correctness is mechanical. Keep those two jobs separate.

The plateau is a pipeline that works only when you personally drive it.

Stage 6 -- Separate Implementation From Review

An agent that reviews its own work in the same context is easy to fool. It knows why it made the change and tends to defend that path.

The project solves this with stage separation. Implementation runs in a ticket clone. Review runs as a separate stage with a different context and surface-specific rules: engine, server, client, workflow docs, agent rules, and skills each have their own review surface. The review stage checks the diff, runs the configured gates, and can send the work back through a follow-up loop.

The run record is the durable bridge between stages. It records what happened: surprises, dead ends, prevention opportunities, verification, and context manifest. A clean implementation without a run record is still a failed run in this project, because nobody can audit or learn from it later.

The plateau is that the machine can now produce more work than a person can comfortably inspect one item at a time.

Stage 7 -- Make The Process Machine-Legible

Once the loop runs continuously, the bottleneck moves from writing code to understanding the system.

The repository now has a DuckDB history index over tickets and run records. The workflow exposes history, history-query, history-search, and history-semantic commands so an agent can ask "what happened before?" without digging through scattered files first. The review config has producer-health watchdogs, soft-check watchdogs, time budgets, spiral detection, and worktree-per-task workspaces.

These are not decorative metrics. They answer operational questions:

  • Which confirmed tickets have no run record yet?
  • Which runs merged cleanly, shipped with escalation, or stalled?
  • Which soft check has gone quiet?
  • Which class of failure deserves a standing rule or a repair ticket?

The plateau is that all of this is still tied to this repository's shell workflow.

Stage 8 -- Extract The Orchestrator

Tempo is the current loop closing back on itself: the orchestrator is being rebuilt as a Go command.

It is not done, and the repo says so. tempo/README.md describes the scaffold, the pinned Go toolchain, the tempo-owned Python runtime, the codemap command, the parity harness, bootstrap assets, and the live ticket engine adapter. The CLI surface in tempo/main.go now includes orchestration verbs such as ticket, review, ship, group-run, history-query, backlog-list, watchdog, and parity. The parity report is careful about its own limits: it checks committed surfaces and lists lifecycle gaps instead of pretending the port has replaced the shell dispatcher.

That honesty is the stage. The system is not merely using AI to build games. It is using the records from AI-built work to build a clearer, more portable system for doing the next work.

How To Use The Map

Do not read the stages as a ladder of status. Read them as a sequence of failure modes.

If your chats rot, control context. If rules get forgotten, make them standing contracts. If work collides, make dependencies and touched surfaces explicit. If agents make unreviewable changes, separate implementation from review. If the same mistake recurs, add a gate, rule, template change, or watchdog. If history is hard to answer, index the artifacts instead of trusting memory.

Two ideas carry most of the weight:

  • Context is spent, not accumulated.
  • Deterministic checks should own deterministic facts.

Everything else in this project is an application of those two ideas: tickets, run records, review stages, soft checks, history queries, and now Tempo.