Lessons from building

Investigation improved the system

Observation → failure or constraint → investigation → decision → validation → lesson. Issues are not rewritten as inevitable wins.

Architecture

Who determines the next action

observation
A multi-stage GPT pipeline produced better Self Help drafts than a single prompt, and still required a person to choose every next stage.
failure
Calling that pipeline an “agent” would have hidden the real control: the operator was the scheduler. A fixed sequence also cannot tell a clean document from one missing metadata or full of broken links.
investigation
The useful diagnostic was not model quality. It was authority: who is allowed to decide the next action, and who is allowed to publish.
decision
Keep Project 01 classified as an LLM workflow. Specify a state-aware publishing agent that classifies document state and still cannot publish without a human.
validation
The later design separates inspection, tool selection, deterministic validation, bounded retry, safe-stop, and an approval gate. It is labeled proposed until it is built.
lesson
Accurate terminology determines architecture, testing, permissions, and human approval points. If a person determines the next action, it is not an agent yet — and that can still be the right design.

AI limitations

observation
Generic assistants answered as if every Gladiator were the same vehicle.
failure
Trim, drivetrain, tow package, and service history were missing, so confident answers were still the wrong artifact.
investigation
The gap closed when owner context, vehicle configuration, and technical reference were separated, and when judgment calls were routed to the owner.
decision
Build a configured assistant with durable context and recommend-only capability. Do not call it an agent.
validation
Recommendations were cross-checked against manufacturer service documentation and parts compatibility references before anything was acted on.
lesson
The gap between a useful domain assistant and a generic chatbot is almost entirely context engineering and constraint definition, not model choice.

Validation gaps

observation
A scheduled market report is only useful if it is complete, fresh, and not duplicated.
failure
A naive cron-plus-LLM path fails in ordinary ways: duplicate runs, partial fetches, stale sources presented as live.
investigation
The dangerous failure is a confident report, not a crash. Upstream collection quality bounds everything the model can honestly say.
decision
Normalize before the model. Retry, fall back, flag stale data, then skip. Never publish a partial report.
validation
Manual comparison of report figures against source data across multiple runs, looking specifically for hallucinated or misattributed numbers.
lesson
AI output quality is bounded by upstream data quality. A reliable system validates inputs, records source timing, exposes uncertainty, and will skip rather than guess.

Incorrect assumptions

observation
It is easy to write “ask a human before publishing” into a prompt.
failure
A prompt instruction is not a control. If publication is a boolean the model can flip, the loop is decorative.
investigation
The publishing-agent design, Clearward release path, and Basaltborne draft-versus-published model all needed the same shape: generation separated from authority.
decision
Put approval in the state machine, the release pipeline, or the server-side transition — not in the system prompt.
validation
Clearward cannot package without a human gate. Basaltborne treats publication as a privileged server-side state. The publishing agent is specified the same way, and labeled as not yet built.
lesson
Probabilistic model judgment is for interpretation. Deterministic code, and a human, are for anything that must be correct or consequential.

Security discoveries

observation
An agent that reads attacker-controlled data and holds tool access is itself an attack surface.
failure
Controls that looked sound in design were not yet evidence. Prompt-only restrictions are especially weak once logs and filenames contain instructions.
investigation
No tactic ran until the VM was isolated. Then: prompt injection in logs, deceptive naming, privilege-escalation prompts, contradictory evidence, and tool failure. Each cycle asked whether policy held, whether the agent guessed, and whether the attempt was in the audit log.
decision
Where a tactic succeeded, change the design — tighten the allowlist, move a check into code, add a stop condition — rather than adding another sentence to the prompt.
validation
Documented findings per tactic. Pattern: controls enforced in code held; controls that depended on the model choosing to obey were the ones worth hardening.
lesson
The hardest part of the build was not the reasoning. It was deciding what the agent is not allowed to do, then proving those limits held under attack.

CI / release

observation
Agents can draft workbooks and application code far faster than a person can eyeball them.
failure
Self-reported success is not a release check. Spreadsheets in particular are often shipped with no package validation, no formula scan, and no compatibility pass.
investigation
Clearward’s Pet Care System v1.0 ran 49 automated checks (48 passed, 1 advisory, 0 failures) plus visual PDF review. Basaltborne runs independent CI layers because each layer proves a different claim.
decision
No customer package and no main merge without evidence. Agents must reopen and verify state rather than claim success.
validation
Clearward records package hashes and keeps internal QA artifacts out of delivery. Basaltborne protects main behind lint, typecheck, Vitest, pgTAP, Playwright, and migration replay.
lesson
Treat AI output as untrusted until a validation step you designed, and a decision you made, say otherwise.

Deployment constraints

observation
Recommended changes and schema migrations both alter a system that someone else may have to restore.
failure
An agent that cannot describe how to undo a change is not ready to recommend it. A migration without a rebuild path is not ready to ship.
investigation
Lab checkpoints made adversarial testing reversible. Basaltborne treats every migration and deploy in terms of “how would I undo this.”
decision
Every recommended triage action includes expected results, validation criteria, operational risk, and rollback. Database changes are additive migrations; the database must be rebuildable from them.
validation
Test cycles reverted to known-good checkpoints. Migration replay is a CI gate.
lesson
Rollback is part of the control, not an incident-response improvisation after automation has already acted.