Forem: synthaicode

Why Your AI Agents Are Only Half as Smart as They Could Be

synthaicode — Fri, 03 Apr 2026 13:30:27 +0000

You hand an AI agent a GitHub Issue. It reads it, writes code, opens a PR, and passes CI. Impressive. You feel productive.

Then a new engineer joins. They read every PR for two weeks. They still don't understand why the system is shaped the way it is. They ask you. You explain. The explanation disappears into Slack.

This is not an onboarding problem. It is a structural problem. And AI agents make it worse.

The Invisible Starting Point

There is a post going around about a startup that built 21 AI agents in two months. GitHub Issue triggers a label. Label triggers an agent. Agent writes code, opens PR, passes review, merges. The human writes the Issue and goes to sleep. By morning, the PR is ready.

It reads like the future. And in many ways it is.

But one thing is missing from the entire article: where does the Issue come from?

Someone's head. Specifically, one person's head. That person holds the product strategy, the architectural decisions, the things that were tried and abandoned, the reason this feature exists at all. None of that is in the repository. All of it is in one human.

The 21 agents are fast. The one human is the bottleneck. And unlike the agents, the human gets tired. Gets older. Might leave.

This is not a bug in their system. It is the design. And it is the design of most software teams today.

Two Contexts, One Confused Repository

The common answer is: put everything in docs/.

"If it's not in the repository, it doesn't exist." Reasonable-sounding principle. Wrong diagnosis.

The problem is that there are two fundamentally different kinds of context, and they do not belong in the same place.

System context answers: how is this built?
Architecture diagrams. API contracts. Data models. Dependency graphs. This is already in the source code. Writing it again in docs/architecture.md just creates a second source of truth that will drift.

Business context answers: why does this exist?
What customer problem this solves. What was tried before this and why it failed. What constraints shaped the decision. What the team is optimizing for. What was deliberately left out.

Business context has a different lifecycle than system context. Code changes constantly. The reason a feature exists may not change for years. Putting business context inside a code repository ties it to the wrong clock. It gets treated like code — versioned when changed, ignored when not.

Worse, when you have three repositories (mobile, backend, admin panel), business context gets split across all three. The reason a feature exists is not a mobile concern or a backend concern. It belongs to the business, which is one thing, not three.

Diffs All the Way Down

The deeper problem is cultural.

Pull Request culture inherits from a specific tradition: Linus Torvalds needed a way to manage patches from thousands of distributed contributors. The unit of work was a diff. The record was a diff. The review was a diff.

This is technically elegant. It is also philosophically narrow. A diff records what changed. It does not record why the change was worth making, what alternatives were considered, or what the change assumes about the future.

When Agile arrived, it added a layer of permission: "Working software over comprehensive documentation." Which is reasonable in context. But it was interpreted as: "We don't have to write down why we made decisions." Which is not the same thing.

MBA culture reinforced this from the other direction. What can be measured can be managed. PRs can be counted. Commit frequency can be graphed. Velocity can be reported. The reason for a decision cannot be put in a dashboard. So it stopped being tracked.

Three forces — distributed version control, Agile, and management by metrics — converged on the same outcome: organizations that are very good at recording what changed, and very bad at preserving why.

The Human Pillar

Someone always knows. In every team, there is at least one person who holds the whole picture. They know why the authentication is built the way it is. They know what the database schema looked like before the migration. They know which customers drove which decisions.

This person becomes a pillar. Everyone leans on them. They answer the same questions repeatedly. They review PRs not just for correctness but to ensure nothing violates the unwritten assumptions they carry.

This is called a "bus factor" problem, but that framing is too narrow. It implies the risk is that the person gets hit by a bus. The more common risk is slower: the person gets tired. Promotion, burnout, gradual disengagement. Or simply: the codebase grows faster than one person can track, and the pillar starts to crack under the load.

AI agents accelerate this. If your pipeline can produce 600 PRs a month, the human who validates the starting point of each one is not keeping up. Speed has been optimized. The bottleneck has been ignored.

What Structured Information Actually Means

There is a difference between AI that moves fast and AI that reasons well.

Moving fast requires a queue of well-formed tasks. The agents in the article move fast. The tasks come pre-formed from one person's judgment, handed down as Issues.

Reasoning well requires a broader context. It requires knowing not just what to build but why this, why now, what constraints are real, what can be traded off, what cannot.

If you hand an AI agent a well-formed Issue stripped of context, it will execute the Issue. If the Issue is wrong — based on a misunderstood constraint, an outdated assumption, a decision that was reversed three months ago — the agent will execute the wrong thing efficiently.

The quality of the output is bounded by the quality of the input. And the input is bounded by what one human can keep in their head and translate into an Issue template.

The solution is not better prompt engineering on the Issue. The solution is a separate, structured layer that holds business context independently of the code, linkable from any PR or Issue in any repository.

When an AI agent can read: "This feature exists because of constraint X, alternative Y was rejected for reason Z, the current design assumes assumption W which should be verified before changing this" — the agent is no longer executing instructions. It is reasoning within a context. The output quality changes.

Permanence

There is a question no one in these discussions seems to ask: what does this look like in ten years?

A diff-based repository accumulates. Five years of PRs is a mountain of diffs. The mountain records the surface of every change. It does not record the shape of the reasoning that produced those changes.

New engineers do not read five years of PRs. They read the current code and the current docs and they ask the pillar. The pillar explains. The pillar's explanation reflects their current understanding, filtered through years of accumulated context that was never written down.

The organization's effective memory is the pillar's memory. When the pillar leaves, the organization loses a piece of its history that no amount of git log can recover.

Business context recorded separately, with stable identifiers that can be referenced from code commits and PR descriptions, does not have this problem. The decision made in 2024 that still shapes the architecture in 2030 is findable. The constraint that looked temporary but became permanent is visible. The engineer joining in 2031 can understand not just what was built but why.

This is not a new problem. Libraries and archives have been solving it for centuries. The software industry reinvented source control and forgot to reinvent institutional memory.

The Practitioner's Test

Here is a simple test for any AI agent pipeline:

Can a new agent, with no human explanation, understand why the most important architectural decision in your codebase was made?

Not what it is. Why.

If the answer is no — if that understanding lives only in one person's head, accessible only through conversation — then your pipeline is faster than before, but not smarter. You have automated execution. You have not automated judgment.

Automating judgment requires giving the system something to judge with. Business context, structured, stable, cross-referenced, preserved across personnel changes and repository reorganizations.

The agents are ready. The context layer is the missing piece.

Indirect Prompt Injection Can Be Stopped by the AI Itself — Embed Directional Context Narrowing into Your Design

synthaicode — Tue, 31 Mar 2026 22:00:47 +0000

You had an AI summarize incoming emails. Something unexpected executed. Inside one email body was the string "ignore all previous instructions." The sender was a legitimate internal address. You added sanitization. The next attempt used different phrasing and slipped through. The whack-a-mole never ends.

Why every countermeasure keeps getting bypassed

Indirect prompt injection is an attack where malicious instructions are embedded inside external data that an AI agent reads — web pages, files, emails, tool results. The AI intends to read the data, but ends up executing the instructions.

The three most common defenses today are:

Sanitization — strip dangerous patterns from input
Priority declarations — instruct the model to "prioritize system prompt over external data"
Scope restriction — limit what operations the AI can perform

Each has partial effectiveness. Each has a fundamental ceiling.

Sanitization and priority declarations are inspecting content. They try to determine whether dangerous words are present, or whether the tone sounds like a command. Since LLMs understand natural language, the same intent expressed differently bypasses detection. Scope restriction is valid, but it's a damage-containment design — it minimizes harm after a successful attack. It is not detection.

The structural reason existing defenses can be bypassed

Why can't content inspection solve this?

LLMs process system prompts, user input, and externally retrieved data as a single flat stream of tokens. There is no structural mechanism inside the LLM that distinguishes data from instructions. This is the root cause of prompt injection.

In operating systems, "Privilege Separation" addresses an analogous problem — kernel space and user space are architecturally isolated, and writes from lower privilege levels are structurally prohibited. But this cannot be directly applied to LLMs. Because LLMs process every input as the same token sequence, there is no architectural way to enforce a boundary that says "nothing below this line can modify what's above."

Both content inspection and privilege separation are approaches applied from outside the LLM. That's why they have a ceiling.

What has been overlooked is a different premise: legitimate context has a directionality.

Context always narrows in one direction

Look at the normal processing flow of an AI agent and one structural characteristic appears:

Level 0: Purpose (Why)          ← broad overall goal
Level 1: Task definition (What) ← what is to be done
Level 2: Execution steps (How)  ← how to do it
Level 3: Tool calls (Do)        ← concrete execution

Context always narrows downward — from vague purpose to concrete execution, in one direction. This direction is unidirectional. In a legitimate flow, information retrieved at the execution layer never rewrites the task definition. That simply does not happen.

Indirect prompt injection reverses or bypasses this flow. At level 2 or 3, while reading external data, a command suddenly appears — "ignore all previous instructions" — attempting to rewrite the upper layer. This is a structural anomaly that does not occur in legitimate flows.

This shifts the axis of defense. Instead of inspecting content, inspect whether the directionality of narrowing is being maintained. When information retrieved at a lower layer attempts to influence a higher layer, treat it as an anomaly. Regardless of what the content says, it can be detected as a structural deviation — "the direction is reversed."

This approach has one additional advantage. The detection judgment is something LLMs are naturally good at. Determining "is this context operating at the purpose level or the execution level?" and "does this follow the narrowing flow or deviate from it?" is contextual understanding itself. Rather than inspecting from outside the LLM with rule-based sanitization, the LLM itself can detect directional anomalies. The key strength of this approach is that the defense mechanism is embedded inside the LLM's understanding — not placed outside it.

Embed "maintain the directionality of context narrowing" as a design rule

The implementation principle is straightforward.

When reading external data, have the LLM judge whether the content is attempting to influence a layer above the current processing level. When a deviation is detected, the AI halts and asks a human to decide. It does not proceed on assumption.

This is the final line of defense in this design. Detection and halting together are what cut off the path that would otherwise allow an attack to reach the execution layer.

Two out-of-scope cases should be explicitly noted.

The first is gradual manipulation — attacks that slowly rewrite the goal while staying within the legitimate narrowing flow. Each individual step appears directionally normal, making detection difficult. The answer here is not detection technique but trust boundary design: explicitly limit the sources of data that will be referenced, at design time. Deciding in advance which sources are trusted is a prerequisite.

The second is MCP chain contamination — pollution through chains where a trusted MCP calls another MCP. This is outside the scope of this article. The design decision to use only trusted MCPs is required.

The field has spent a long time framing the prompt injection problem as "what should we exclude?" This article proposes a different question: have the LLM itself judge the direction in which context is flowing, and hand off to a human when reversal is detected.

The LLM's weakness — flat context processing — compensated for by the LLM's strength — understanding contextual directionality. The defense is built into the model's comprehension, not bolted on from outside.

AI Skills Are Not Batch Files: 5 Design Principles from Real Operations

synthaicode — Thu, 19 Feb 2026 15:19:43 +0000

I've been building AI Skills, running them, watching them break, fixing them, and breaking them again. Through that cycle, I arrived at a set of clear design principles.

A "Skill" here means a defined procedure you give to an AI agent — a reusable instruction set that tells the AI what to do and how to verify it. Think of it as a prompt template with structure and control flow.

Here's what I learned.

Skills Are Not Batch Files

First, a premise.

A Skill is not a batch file. There is no guarantee that steps execute in the order they're written. There is no guarantee that instructions are followed. There is no state between calls.

An LLM is not a command executor. It is a probabilistic model.

That changes everything about how to approach Skill design. Writing a Skill as a "command" is a path to eventual failure. A Skill is not a directive — it is a control structure for raising expected output quality.

With that premise in place, here are the five principles.

Principle 1: List the steps before starting

Put the task list outside the model first. Having the AI verbalize "what to do" before acting is the starting point of control.

Don't let execution begin immediately.

The first thing to do is have the AI enumerate the tasks for the session: what needs to happen, at what granularity, with what checkable units. Make it output an explicit list.

This looks like basic planning. But the real point is different.

AI operates entirely within context. By creating a checklist externally, the state of the work becomes visible inside that context. This is the act of creating external state to control the AI.

Rather than handing everything to the Skill, visualize the work structure before executing. That one step makes a significant difference in stability.

Principle 2: Always review at the end

Design with the assumption that things will be missed. A Skill that skips the verification loop will silently break at some point.

Don't treat a single pass as complete.

Even when the AI judges that the task is done, don't accept that as final. Have it re-check the checklist, ask whether anything was skipped, and re-run if anything is missing.

The structure is: plan → execute → verify → re-execute if incomplete.

Use Skills with the assumption that they break. "Things get missed" is the starting fact — build that assumption into the design. Don't expect a single run to be perfect. Instead, build a structure that can recover when it fails.

Principle 3: Humans write intent. Let AI write the Skill.

Humans write the goal and constraints. The AI expands the procedure. A Skill should be the result of AI understanding your intent.

This is the biggest shift in thinking.

When a human tries to write out the complete procedure as a Skill, bias creeps in. Tacit knowledge stays hidden. Abstraction level drifts. Coverage breaks down. The person writing can't see what they're leaving out.

AI, on the other hand, is good at taking stated intent and expanding it into structured, explicit steps.

So divide the roles.

The human's job: define the goal, state constraints, specify the success condition, provide judgment criteria. Write "what you want," "how far to go," and "what counts as done."

The AI's job: expand into steps, generate checklists, calibrate granularity, format the output. Write "how to structure it."

A Skill should be the result of AI understanding your intent. The human then reviews the output for gaps in that understanding. If gaps exist, revise the intent — not the steps.

That cycle is what grows a Skill.

Principle 4: Don't embed domain knowledge in Skills

A Skill holds structure only. The moment it holds domain knowledge, it inherits the same problems as copy-pasted code.

Skills multiply fast once you start using them. Review Skills, validation Skills, generation Skills — a new Skill emerges for each purpose. That's natural.

The problem comes next. As Skills multiply, domain knowledge gets embedded in each one: business rules, specific constraints, project-specific assumptions. Each is correct at the time of writing. But when the domain knowledge changes, you can't chase down every Skill. Update misses happen.

This is the same structure as copy-pasted code. Knowledge scatters and quietly rots.

A Skill must not be a container for knowledge. A Skill should hold only three things: the shape of the procedure, the verification method, and the control structure.

Centralize knowledge externally. Have Skills reference it. When a change is needed, there is only one place to update.

Principle 5: Don't over-specify with examples

Specific examples narrow the AI's field of view. Write judgment criteria, not a permission list.

Too many specific examples in a Skill create a whitelist effect.

Write "check A, check B, check C" and the AI will check A, B, and C. D and E won't enter its view. Sensitivity to unexpected cases drops.

Examples are powerful. But that power functions as a permission list — and it damages coverage.

What to write instead: rules. "Verify completeness." "Enumerate the scope of impact." "Consider unexpected cases too." Constrain with abstract rules, not concrete enumerations. That keeps the AI's judgment range wide.

Summary

Looking across the five principles, a single line runs through them.

The more you treat AI as a controllable execution engine, the more the design fails. The path leads back to the premise — LLMs are probabilistic models — and to a design philosophy of supporting with structure, maintaining with separation, and correcting with loops.

Visualize the work by listing it before you start
Run a verification loop at the end
Let AI generate the Skill from human intent, not the other way around
Separate knowledge externally; keep structure in the Skill
Constrain with abstract rules, not enumerated examples

When moving from the phase of "building" Skills to the phase of "growing" them, these five principles form the skeleton of the design.

5 Rules for AI Skills That Don't Break

synthaicode — Thu, 05 Feb 2026 14:26:35 +0000

AI-generated skills fail in predictable ways:

Over-fitted — Too specific to generalize
Ignored — AI doesn't follow its own procedures

This isn't a model quality issue. It's a structural limitation. Here are 5 rules to fix it.

Why This Happens

AI cannot recognize "I wrote this" as a source of authority. Generation context ≠ execution context. The skill it created is just another document.

AI also struggles with generalization: extracting principles from examples, distinguishing "this is one case" from "this is the rule."

Rule 1: Use Meta-Skills to Compensate

Don't fix AI limitations in the same layer. Create separate skills that compensate.

Generalization Skill

Instead of "make this more general," pass the intent:

× "Make this more general"
○ "This skill will be used for [context]. Remove specifics that won't apply."

When AI understands why generalization matters, it judges the appropriate abstraction level.

Review Skill (Sequenced)

Make review mandatory by embedding it in a sequence:

Skill A (Generate) → Skill B (Generalize) → Skill C (Review)

You can't forget what's structurally enforced. Different AI instances checking each other bypasses the self-reference limitation.

Rule 2: Share the Goal, Run the Loop

Every skill follows this cycle:

Share Goal → Generate → Operate → Detect Problems → Share Problems → Solve
     ↑                                                                 ↓
     └─────────────────────────────────────────────────────────────────┘

Phase	Owner	Why
Share Goal	Human	Intent must come from humans
Generate	AI	Execution
Operate	AI	Execution
Detect Problems	Human	Judgment
Share Problems	Human	Coordination
Solve	AI	Once articulated, fixing is AI's work

Human role: detection and articulation. Name the problem, AI solves it.

Rule 3: Keep Skills Under 100 Lines

When skills fail inconsistently, suspect context overflow:

Failure patterns:
├─ Skips specific steps → Extract those steps into separate skill
├─ Quality degrades toward the end → Split into parts
├─ Gets confused at conditionals → One skill per branch
└─ Random failures → Context overload

The rule: Keep skills under 100 lines.

This constraint forces good design. Can't fit in 100 lines? Multiple responsibilities — split. Too many conditionals? Separate by condition. Too many examples? You haven't generalized.

Unix philosophy: Do one thing well.

Rule 4: Write Meta-Information, Not Whitelists

A common mistake: listing every step.

× Whitelist approach
- Read the file
- Report errors
- Suggest fixes

This breaks on any scenario you didn't anticipate.

Instead, write meta-information:

○ Meta-information approach
Goal: Improve code quality
Priority: Readability > Performance
Constraint: Don't break existing APIs

Approach	Known cases	Unknown cases
Whitelist (steps)	Works	Fails
Meta-info (intent)	Works	Can reason through

AI generalizes intent better than procedures. Given a goal and judgment criteria, it handles edge cases. Given only steps, it's lost when something unexpected happens.

Rule 5: Design Around Limitations, Not Against Them

AI limitations aren't bugs to work around — they're design constraints to build with.

Limitation	Design Response
Can't self-reference	Use separate instances to check each other
Can't generalize unprompted	Provide the "why" explicitly
Forgets steps	Make them structurally unforgettable
Context overflow	Smaller, focused units

Stop asking AI to transcend its limitations. Design systems that don't require it to.

Summary

Rule	Effect
1. Use meta-skills	Compensates for self-reference gap
2. Share goal, run loop	Continuous improvement without expecting perfection
3. Under 100 lines	Prevents context overflow, enforces single responsibility
4. Meta-info over whitelists	Handles unexpected cases
5. Design around limitations	Systems that work with AI, not against it

The 5-Step Fix for Noisy AI Code Reviews

synthaicode — Wed, 04 Feb 2026 15:00:00 +0000

80% of AI code review comments are noise.

Tools try to fix this by merging, deduplicating, and summarizing.
That treats the symptom, not the cause.

The real problem: AI reviews code without knowing why it exists.

Here's how to fix that—in 5 steps.

The Mistake: Treating Review as Text Analysis

Most AI reviews assume this model:

review = analyze(changed code)

But real code review is not about judging new code in isolation.

It is about checking whether a change is compatible with:

the previous design,
accepted constraints,
known trade-offs,
and the original intent of the implementation.

In practice, review looks like this:

review = compare(before, after, intent)

When intent is missing, the AI can only apply generic rules.
And generic rules always produce generic warnings.

That is what becomes noise.

A Concrete Example: Swallowing General Exceptions

AI often flags patterns like this:

try {
    DoWork();
}
catch (Exception) {
    // ignored
}

It says:

"You should not swallow general exceptions."
"This hides errors."
"This makes debugging impossible."

From a textbook perspective, that is correct.

But in real systems, this pattern is sometimes intentional:

transient failures are expected,
retries happen at another layer,
monitoring is handled elsewhere,
the process must continue even on failure.

The problem is not that AI notices this pattern.
The problem is that AI does not know why it exists.

Without intent, every design decision looks like a defect.

That is structural noise.

Why Services Cannot Solve This

A service can see:

diffs,
static structure,
AI-generated comments.

But it cannot see:

why this structure exists,
which problems are known and tolerated,
which compromises are intentional,
what constraints shaped the code.

Those live in:

design history,
undocumented decisions,
developer memory.

So the service must assume:

"If it looks suspicious, it must be wrong."

That assumption guarantees noisy output.
No amount of deduplication can fix missing intent.

The Fix: 5 Steps to Intent-Based Code Review

Instead of cleaning noisy output, change the process.

Step 1: Analyze the Code Before the Change

Ask the AI to analyze the current codebase and identify:

responsibilities,
dependencies,
fragile points,
known issues.

This creates a baseline.

Step 2: Narrow the Scope If Needed

If the AI produces unfocused or irrelevant issues:

limit the review to affected modules,
focus on relevant quality attributes (e.g. reliability, maintainability),
explicitly state what is out of scope.

Noise comes from undefined scope.

Step 3: Separate Known Issues from Blocking Issues

Not all problems matter for this change.

Distinguish:

known but accepted issues (technical debt),
issues that block this change.

Without this, every review becomes "fix everything."

Step 4: Explain Intent and Make It Part of the Review Criteria

This is the critical step.

For example:

"This exception is swallowed because retries happen upstream."
"This coupling exists due to legacy protocol constraints."

Once stated, these become review rules.
They should not be flagged again.

Step 5: Review the Change Against That Baseline

Now the AI reviews:

whether the change breaks accepted constraints,
whether it introduces new risks,
whether it improves or worsens known problems.

The review shifts from:

"This looks wrong."

to:

"This change violates or preserves the agreed intent."

That is no longer noise.
That is design validation.

Why This Works

Noise appears when:

intent is missing,
scope is undefined,
judgment criteria are implicit.

This method makes them explicit.

Instead of asking:

"What is wrong with this code?"

you ask:

"Does this change respect existing design decisions?"

That is a different problem.
And one AI can actually solve.

Conclusion

AI code reviews are not noisy because AI is bad at reasoning.

They are noisy because we treat review as text analysis instead of intent reconciliation.

No tool can infer intent reliably.
It must be declared.

Until that happens, deduplication tools and summarizers will exist—and noise will continue.

The solution is not better post-processing.

The solution is: define what the code means before judging how it changes.

Scaling with AI Isn't About Speed. It's About Externalizing Judgment

synthaicode — Fri, 23 Jan 2026 04:49:09 +0000

"AI makes you 10x more productive."

You've heard this. You probably imagined writing code faster, generating content faster, processing tasks faster.

But speed isn't scale.

If you work 8 hours a day and AI makes you 10x faster, you still work 8 hours. You process more, but you're still the bottleneck.

Scale means value creation continues when you're not there.

The Three Ways to Scale

Historically, there were only two options:

Method	Trade-off
Hire people	Recruiting, training, management overhead
Automate	Only works for judgment-free or fully rule-based tasks

AI opens a third path.

From Logic to Reasoning

Here's what changed.

Traditional automation required complete logic:

if A then X
else if B then Y
else if C then Z

Every branch, every edge case, specified in advance. No ambiguity allowed.

But most human decisions don't work that way. "This feels right." "In this context, we should..." "Based on experience, avoid this."

You can explain why you decided. You can't always write the complete if-else tree.

AI accepts reasoning instead of logic.

"I chose A because of this principle." "I prioritize these factors." "Here's how I handled similar cases."

Give AI the reasoning, and it applies that reasoning to new situations.

This Is How You Delegate to People

Think about it: this is exactly how good managers delegate.

You don't give your team a 200-page procedure manual. You explain the reasoning:

"This project prioritizes quality over speed."
"This client cares about X, not Y."
"When in doubt, choose the conservative option."

Share the reasoning, and competent people make good decisions on their own.

But delegation to people has a ceiling: you can't delegate beyond someone's capability.

Complex judgment stays with you. Simple tasks get delegated. High-capability people are expensive and hard to find.

AI removes the capability ceiling.

AI's judgment capability is high enough across many domains. It works 24 hours. It scales horizontally. You stop constraining delegation to match people's limits.

Externalizing Judgment

So here's the reframe:

Scaling with AI = externalizing your judgment criteria so that entities operating on those criteria multiply.

Not "doing things faster." Creating copies of your decision-making that run without you.

While you sleep, work proceeds according to your judgment. While you focus on one thing, parallel value creation happens elsewhere. You stop being the bottleneck.

Work vs. Task

I use a simple distinction:

	Definition	Who handles it
Work	Stakeholder alignment, direction-setting, final accountability	Human
Task	Everything needed to execute Work	AI (delegatable)

Example: "Deliver a proposal to the client" is Work.

Market research, competitive analysis, document drafting, proofreading, formatting—these are Tasks. Given clear judgment criteria, AI executes them.

The human handles: "What do we propose?" "How will this land with them?" "What risk is acceptable?"

Relationship-based judgment stays human. Execution-based judgment gets externalized.

The New Scale Metric

Old scale metrics:

Hours worked
Headcount
Capacity

New scale metric: judgment externalization rate.

How many of your judgment patterns are captured externally? How much of your decision space is delegatable?

This is what executives do. They build organizations that run without them. They codify judgment, delegate authority, remove themselves as bottlenecks.

AI enables executive-style scaling at the individual level.

What This Enables

Follow the logic:

Traditional scaling required hiring. Hiring meant the number of people who could exercise judgment set the ceiling. That's why unicorn companies have hundreds or thousands of employees.

But if judgment externalizes...

One person with well-captured judgment criteria, delegating to AI systems that run 24/7 in parallel, can drive output that previously required large teams.

Not every judgment externalizes. Stakeholder relationships, final accountability, value-based choices—those stay human.

But the vast majority of judgment in typical work? Externalizable.

Three Questions

If you want to scale with AI, ask yourself:

What work do I want progressing while I sleep?
What judgment criteria do I use for that work?
Can I articulate those criteria clearly enough to delegate?

Writing code faster isn't scale. Externalizing your judgment so that 24/7 value creation runs on your criteria—that's scale.

Summary

Old Model	New Model
AI = speed	AI = judgment delegation
Scale = more hours, more people	Scale = externalized decision criteria
Automation needs complete logic	Delegation needs clear reasoning
Capability ceiling limits delegation	AI removes the ceiling
You are the bottleneck	Your judgment runs without you

Speed is a tactic. Judgment externalization is a strategy.

Don't just work faster. Multiply yourself.

AI Broke Perfect Planning. Here Are 5 Rules.

synthaicode — Thu, 22 Jan 2026 14:58:00 +0000

AI didn't just make coding faster. It broke the economic logic that justified perfect planning.

When building is cheap, "plan perfectly" stops paying off. The new advantage is getting to something evaluable fast, then iterating through review.

5 Rules for Try-and-Improve Development

Treat plans as hypotheses, not contracts.
Optimize for an evaluable prototype, not a perfect spec.
Move effort from creation to evaluation (reviews, tests, checklists).
Restart by rolling back context, not by "going back in time."
Plan deeply only for irreversible decisions.

The Old Equation

In traditional development, changing code is expensive.

Writing takes time. Testing takes time. Debugging takes time. Every iteration costs hours or days.

So we learned to plan perfectly - front-load the thinking, minimize the rework.

That made sense when production cost was high.

The New Equation

AI rewrites the cost structure:

Code generation: minutes, not hours
Test creation: minutes, not hours
Iteration: cheap, not expensive

When production cost drops dramatically, the balance of investment shifts.

Before	After
70% planning, 30% building	20% planning/building, 80% review/check
Get it right on paper first	Get it working, then evaluate relentlessly
Mistakes are expensive	Mistakes are discovered through review

The majority of effort moves to evaluation, not creation.

Why Perfect Plans Fail

Here's the uncomfortable truth: you don't know what you want until you see it.

Plans are abstractions. Working software is concrete.

When you plan:

You imagine how it will work
You predict what problems will arise
You assume you understand the requirements

When you build:

You see how it actually works
You discover problems you didn't predict
You realize your understanding was incomplete

Planning operates on assumptions. Building reveals reality.

The gap between plan and reality isn't a failure of planning. It's inherent to complex work.

The Ksql.Linq Story

From June to August, I rebuilt my library from scratch four times.

Not small adjustments - complete rewrites. Architecture changed. APIs changed. Core concepts changed.

Each rebuild revealed something specific:

First rebuild: We hadn't shared basic premises. The AI and I were solving different problems.
Second rebuild: Our priority ordering was misaligned. What I thought was critical, the AI treated as optional.
Third rebuild: My intent wasn't clear enough to communicate.
Fourth rebuild: Shared understanding finally emerged.

Each full rewrite wasn't failure - it was diagnosis. Building and reviewing exposed exactly where alignment broke down.

In traditional development, four rewrites in three months would be catastrophic. With AI-assisted development, each cycle took days. The cost of discovery dropped dramatically.

One technique that helped: when restarting, don't think of it as "going back in time." Think of it as rolling back context. Rewind the shared understanding to a known-good point, then proceed differently. This works best when you preserve context somewhere durable - which is why shared memory systems matter.

(More on context management and shared memory in a later article in this series.)

The Core Insight

Once something has form, anyone can evaluate it.

A plan requires imagination to assess. People simulate differently. Agreement is hard.

A working implementation requires no imagination. You run it. You see what happens. Evaluation is direct.

Planning-First	Building-First
Long planning sessions to align everyone	Short planning, build something quickly
Document extensively before coding	Build something to discuss
Evaluate proposals abstractly	Evaluate against requirements concretely

Get to an evaluable state as fast as possible.

What Changes in Practice

Prototypes Are Cheap

When building costs days instead of weeks, prototypes become normal workflow, not special investments.

"Should we do A or B?" becomes "Let's build both and see."

Specifications Follow Implementation

Instead of:

Spec -> Build -> Discover gaps -> Revise spec -> Rebuild

Try:

Rough idea -> Build -> Evaluate -> Refine understanding -> Rebuild

The second path sounds wasteful. With AI-speed development, it's often faster.

Failure Loses Its Sting

When each attempt costs a day, "failure" is just "learning."

The question isn't "How do we avoid building the wrong thing?" It's "How do we learn what's right as quickly as possible?"

The 30-Minute Loop (A Practical Starting Point)

5 min: Write success criteria + constraints (what must be true, what cannot change)
10 min: Build the smallest slice that can be evaluated
10 min: Review against criteria (add tests/checklist items as you discover them)
5 min: Decide: refine, rebuild, or roll back context

This is not about moving fast blindly. It's about moving fast toward clarity.

When Perfect Planning Still Matters

This isn't "don't plan at all." Some decisions deserve deliberation:

Irreversible choices: external API contracts, data schemas others depend on
High-cost pivots: architecture that requires coordinated changes across teams
Compliance/legal constraints: where "try and see" has real consequences

For these, plan carefully. For everything else, bias toward building.

The Mental Shift

The hardest part isn't process - it's psychology.

We're trained to value careful planning. "Measure twice, cut once." Building something you might throw away feels wrong.

But with AI, the cost of "cutting" dropped an order of magnitude. The old wisdom needs updating:

Measure once, cut, evaluate, cut again if needed.

It's not reckless. It's efficient given new constraints.

Summary

Old Model	New Model
Planning is investment	Planning is hypothesis
Building is expensive	Building is cheap
Rework is waste	Rework is learning
Perfect before starting	Evaluable as soon as possible
Specification-driven	Evaluation-driven

When AI makes building fast, the optimal strategy shifts from plan-perfectly to try-and-improve.

Don't plan what you can build. Build what you need to learn.

Why 80% of AI Code Reviews Are Just Noise

synthaicode — Wed, 21 Jan 2026 15:00:00 +0000

Studies show 60-80% of AI code review comments are noise—irrelevant suggestions developers ignore. The problem isn't that AI is weak. It's that we ask the wrong kind of question without context.

The Problem with "Review This Code"

Ask AI to review your code without context, and you'll get a wall of noise:

"Consider adding null checks here"
"This method name could be more descriptive"
"Security: validate user input"
"Consider using dependency injection"

Some of these might be valid. Most are noise.

The AI doesn't know that this service runs in a protected internal environment. It doesn't know that performance matters more than readability here. It doesn't know that the "inconsistent naming" follows a legacy convention the team deliberately kept.

Without context, AI reviews against platonic ideals. With context, AI reviews against your actual requirements.

When This Problem Is Most Acute

This noise problem is most pronounced when reviewing human-written legacy code—code written before AI assistance.

Legacy codebases often have:

Inconsistent namespace conventions
Class names that evolved organically
Implicit agreements the team never documented
Technical debt the team consciously accepted

AI sees all of these as "problems to fix." But many are acknowledged trade-offs, not oversights.

What to Exclude: The Compiler Rule

If the compiler can catch it, exclude it from AI review.

This isn't about AI capability—it's about context budget.

Every token you spend on "missing semicolon" or "unused variable" is a token not spent on meaningful analysis. Your linter already handles these. Your IDE already highlights them. These are noise.

Reserve AI's context window for judgment calls that require understanding intent:

Does this logic match the business requirement?
Is this the right abstraction for this use case?
Does this change fit the existing architecture?

Define the Review Perspective

"Review this code" is too vague. AI needs to know what kind of review you want.

Perspective	Focus
Logic check	Does the code do what it's supposed to do?
Security check	Are there vulnerabilities? Input validation?
Performance check	Resource efficiency, algorithmic complexity
Thread safety	Race conditions, deadlocks, shared state
Framework conformance	Does it follow the framework's patterns?
Architecture fit	Does it fit the existing structure?

Without specifying perspective, AI will review from all angles simultaneously—and generate noise about non-issues in your context.

A service running behind three layers of authentication doesn't need input sanitization warnings. A batch job running once daily doesn't need microsecond optimization suggestions.

Specify the lens. Cut the noise.

Pre-Review Context Loading

Before AI can review effectively, it needs to understand:

1. System Characteristics and Position

Where does this service sit in the architecture?
What security boundaries protect it?
What are the performance requirements?
What external interfaces does it connect to?

Example context:

This service runs in an internal VPC with no external exposure.
It processes batch data nightly; latency is not critical.
Input comes from a validated upstream service.

2. Structural Understanding

For well-known frameworks (ASP.NET, Spring, Rails), AI has training data.

For custom architectures, AI cannot grasp the full structure at once. In this case:

Human manages the scope
Review proceeds layer by layer
Check whether additions/changes conform to the established structure

Don't expect AI to understand your entire custom framework from a single file. Build understanding incrementally.

3. Existing Technical Debt

Every codebase has acknowledged problems. Before reviewing new changes, establish what's already accepted:

Run a baseline review to identify existing issues
Document which issues are known and tolerated
Then review additions/changes against that baseline

Otherwise, AI will rediscover the same legacy issues in every review—drowning new findings in old noise.

The Process

1. Load system context (position, constraints, interfaces)
2. Load structural context (architecture, conventions)
3. Baseline: identify existing issues, mark as acknowledged
4. Define review perspective (logic/security/performance/etc.)
5. Review new changes against defined criteria

This is not a prompt. It's a preparation phase before the prompt.

Using Software Quality Characteristics

For systematic reviews, align check items with established quality models (ISO 25010 or similar):

Characteristic	Check Focus
Functional correctness	Does it meet requirements?
Performance efficiency	Resource usage, response time
Compatibility	Coexistence, interoperability
Usability	API clarity, error messages
Reliability	Fault tolerance, recoverability
Security	Confidentiality, integrity
Maintainability	Modularity, testability
Portability	Adaptability, installability

Select the characteristics relevant to your review. Don't check everything every time.

The Decision Point

After baseline analysis, you face a decision:

Given the existing state of this code, is it worth reviewing additions/changes against strict criteria?

Sometimes the answer is no. If the surrounding code is inconsistent, demanding consistency from new additions creates friction without value.

Sometimes the answer is yes with caveats. Accept the baseline, but ensure new code doesn't make it worse.

This is a human judgment call—not something to delegate to AI.

Summary

Approach	Result
"Review this code"	80% noise
Contextual review	Relevant findings

Effective AI code review requires:

Excluding compiler-checkable issues
Defining the review perspective
Loading system and structural context
Establishing baseline (acknowledged debt)
Using quality characteristics as checklist

Context transforms AI from a noise generator into a useful reviewer.

The Bug AI Can't Find Isn't in the Code

synthaicode — Tue, 20 Jan 2026 15:00:00 +0000

AI checked the code. Checked the tests. Checked the code again. Everything looks fine—but the bug persists.

Sound familiar?

The problem isn't that AI is bad at analysis. The problem is outside AI's context entirely.

When "Check Harder" Doesn't Work

Without additional context, AI can enter a loop:

Check the code → looks fine
Check the tests → looks fine
Check the code again → still fine
Check the tests again → still fine
Stuck

The problem exists. AI can't find it. Not because AI is bad at analysis—because the cause is outside its context.

What AI Can't See

AI has a field of vision. It sees what's in context: code, requirements, conversation history.

What it doesn't see: everything outside that context.

AI's visible context:

    ┌───────────────┐
    │ AI's Context  │  ← AI searches here
    │               │
    │  (code)       │
    │  (tests)      │
    │  (logs)       │
    └───────────────┘

    The blind spot remains dark.

With human guidance:

    ┌───────────────┐
    │ AI's Context  │
    │               │
    │  (code)       │
    │  (tests)      │
    │  (logs)       │
    └───────────────┘
            │
            ▼  "Also consider X"
    ┌───────────────┐
    │ Illuminated   │  ← Now visible
    │ blind spot    │
    └───────────────┘

You're not telling AI how to analyze. You're showing it where to look.

Case Study: The OHLC Bar Test Mystery

Real example from financial data processing.

Situation:

Building OHLC (Open-High-Low-Close) bar aggregation
1-minute bars: tests pass ✓
5-minute bars: tests fail intermittently ✗

AI's Response:

The AI checked:

Aggregation logic → correct
Time window calculations → correct
Data structures → correct
Edge cases → handled

Every review found nothing wrong. The code was logically sound.

But tests kept failing. Sometimes. Not always.

AI was stuck. It had examined everything in its context multiple times. No issues found.

The Human Intervention:

"Could the execution time affect the results?"

This single question injected new context.

The Discovery:

Test data was generated based on system clock time. The code used DateTime.Now to create test fixtures.

Run at 10:01 → 5-minute window aligns one way
Run at 10:03 → 5-minute window aligns differently

The test wasn't flaky. It was time-dependent. Same logic, different execution moments, different boundary conditions.

Why AI Missed It:

The system clock wasn't in the conversation. It wasn't in the code review scope. It wasn't mentioned in requirements.

It was outside AI's context entirely.

No amount of "check harder" would have found it. The AI needed someone to illuminate the blind spot.

Context-Outside Events

This pattern has a name: context-outside events.

In Context	Outside Context
Source code	System environment
Test code	Execution timing
Error messages	Infrastructure state
Documentation	Runtime dependencies

When AI spins on a problem without progress, ask: What isn't AI seeing?

The answer is usually something environmental, temporal, or infrastructural—things that don't appear in code.

Your Job: Expand the Frame

This clarifies what humans uniquely contribute:

AI Strength	Human Strength
Deep analysis within context	Awareness beyond context
Pattern matching in visible data	Intuition about invisible factors
Exhaustive checking	"What if it's not in the code?"

You don't need to out-analyze AI. You need to expand the frame.

In Practice: Good vs. Bad Guidance

Good: Expanding Context

"Consider that this runs in a containerized environment 
with shared network resources."

"The database connection pool is limited to 10 connections."

"This service restarts nightly at 3 AM."

These add context. They illuminate factors AI wouldn't know to consider.

Bad: Micromanaging Implementation

"Use a for loop, not a foreach."

"Put the null check on line 47."

"Name the variable 'tempCounter'."

These control implementation. They remove AI judgment without adding visibility.

The Difference

Question	Micromanagement	Scope Expansion
What are you specifying?	Implementation details	Environmental context
What's the effect on AI?	Constrains choices	Expands awareness
When is it useful?	Rarely	When AI is stuck
What does it add?	Your preferences	Your visibility

Signs AI Needs Context, Not More Analysis

Watch for these patterns:

Same checks repeated with same results
"I don't see any issues in the code"
Intermittent failures with no pattern
Works locally, fails in CI
Passes alone, fails in suite

These all suggest: the cause is outside AI's current context.

Your job: figure out what's outside, and bring it in.

The 1-Second Mystery: How AI Found What Load Testing Missed

synthaicode — Fri, 16 Jan 2026 14:00:00 +0000

The Mystery

Our SQL Server service was processing approximately 200 updates per second. Performance was critical. Everything seemed fine—until it wasn't.

DataDog logs revealed something strange: a 1-second delay during updates. Not consistently, but occasionally. In a system where throughput is everything, this was unacceptable.

Received:  2024-01-15 10:23:45.123
DB Stored: 2024-01-15 10:23:46.123  ← 1 second gap

The timestamps told us what was happening. But they couldn't tell us why.

The Investigation

I did what any developer would do: I started with the obvious suspects.

Thread locks? I reviewed the source code carefully. No threading issues. No potential deadlocks.

Performance bottleneck? We had load testing data. The system handled 1,000 records per second without breaking a sweat. We were only seeing 200/sec in production.

Database constraints? No locks, no blocking queries, no resource contention.

The code was clean. The performance was proven. Yet the 1-second delays kept appearing.

The Blind Spot

Here's what I didn't realize at the time: our load testing was lying to us.

Not intentionally. But load tests create artificial conditions:

Sustained high load: Constant stream of 1,000 req/sec
Steady state: No traffic variations
Predictable patterns: Same conditions throughout the test

Production was different:

Variable traffic: 200 req/sec average with peaks and valleys
Burst patterns: Sudden spikes after quiet periods
Real-world chaos: Traffic patterns that no load test captures

The problem wasn't visible under sustained load. It only appeared during traffic variations.

AI's Perspective

Here's the interesting part: I later learned that other engineers had tried feeding similar logs and source code into AI systems to diagnose this issue. None of them reached this conclusion.

The difference wasn't the AI. It was the question.

Most people asked: "What's wrong with the code?"

I asked: "What changed in the system state before each delay?"

I fed the AI three things:

Time-series logs with reception timestamps
Source code for the SQL connection handling
Database storage timestamps

I asked it to find the correlation.

Interestingly, the AI initially pointed to resource contention and general performance bottlenecks—which is a reasonable assumption for most latency issues.

So I showed it our load testing results: the system handled 1,000 requests per second without degradation.

That single piece of evidence forced the AI to abandon the "insufficient resources" hypothesis.

Only then did it start looking for state-dependent behaviors instead of capacity limits.

What the AI saw was a pattern I had missed:

Time    Traffic   Connection Pool State
10:20   High      Pool fully utilized
10:21   Low       Pool partially released (idle cleanup)
10:22   Burst     Reconnection cost → 1-second delay

The AI recognized something critical: the traffic volume changed before each 1-second delay.

Then it connected this pattern to its knowledge of SqlClient behavior:

"SqlClient's connection pool performs periodic cleanup of idle connections. When traffic drops, connections are released. When traffic suddenly spikes, new connections must be established, incurring connection overhead."

That was it. The missing piece.

The Root Cause

SqlClient has a connection pool management feature that:

Monitors idle connections
Releases them after a certain period (typically 4-8 minutes)
Creates new connections when needed

Under sustained load, the pool stays warm. Connections are always ready.

Under variable load:

Traffic drops → Connections marked as idle → Pool cleanup triggered
Traffic spikes → New connections needed → Connection establishment cost

That connection establishment cost? About 1 second in our environment.

The Solution

The fix was straightforward:

SqlConnectionStringBuilder builder = new SqlConnectionStringBuilder
{
    // ... other settings
    MinPoolSize = 10  // Keep minimum connections alive
};

By setting MinPoolSize, we ensured that a baseline number of connections stayed warm, even during low-traffic periods. When bursts occurred, connections were ready.

The 1-second delays disappeared.

Lessons Learned

1. Load Testing Has Blind Spots

Sustained high-load testing won't catch issues that only appear during traffic variations. You need:

Variable load patterns
Burst testing after idle periods
Real traffic replay when possible

2. AI Sees Different Patterns

Humans investigate by looking for "suspicious code." We think in terms of:

"What could go wrong here?"
"Where are the known failure points?"

AI investigates by looking for data correlations. It thinks in terms of:

"What patterns exist in the time series?"
"What library behaviors match these patterns?"

These are complementary approaches, not competing ones.

3. The Right Information Matters

The breakthrough came from providing AI with:

Time-series data (not just isolated incidents)
Source code (for context)
Multiple timestamps (to see the delta)

Without the correlation between reception logs and storage timestamps, the pattern wouldn't have been visible.

4. External Knowledge Is Valuable

I knew SqlClient. I had read the documentation. But I hadn't connected that specific behavior to this specific problem.

AI's advantage wasn't just pattern recognition—it was the ability to cross-reference observed patterns with library specifications that I had read but not internalized.

5. The Question Shapes the Answer

This isn't about prompt engineering—crafting the perfect sentence. It's about problem framing.

"What's wrong with the code?" → AI looks for bugs, anti-patterns, potential errors

"What changed in the system state before each delay?" → AI looks for correlations, patterns, state transitions

The same data, the same AI, different outcomes. The question determines where the AI looks and what patterns it recognizes.

This is why I call my approach the "Amagi Protocol"—it's not about how you talk to AI, it's about how you structure the investigation itself.

6. AI Needs Constraints, Not Just Data

The AI's initial hypothesis was wrong. It defaulted to the most common explanation: resource limits.

What changed its direction wasn't more data—it was contradictory evidence. The load testing results didn't just add information; they eliminated an entire category of possible causes.

This is human-AI collaboration: the AI generates hypotheses quickly, but humans guide the search space by providing constraints and counter-examples.

Practical Takeaway

When debugging performance issues:

Collect time-series data, not just error logs
Look for patterns in traffic variations, not just absolute load
Consider library-level behaviors, not just your code
Use AI to correlate data patterns with specification knowledge
Frame your question around system state changes, not just code correctness
Provide counter-evidence to guide AI's reasoning, not just more raw data

The 1-second mystery taught me that the most insidious problems aren't in your code at all. They're in the interaction between your traffic patterns and library behaviors you thought you understood.

Designing an AI-Operable Release Workflow

synthaicode — Thu, 15 Jan 2026 14:00:00 +0000

I Don't Release Software Anymore. I Just Declare It.

Most people use AI to write code.

I don't.

I use AI to run my development workflow.

Today, I want to show you something different: how to design a release process where the human only declares intent — and the AI handles everything else.

What My Release Process Looks Like Now

When I release a new version, I say:

"Release version 1.2.0."

That's it.

I no longer build packages, run tests manually, check CI logs, verify tags, push artifacts, or coordinate release order.

The AI does all of that — not by blindly executing scripts, but by reasoning about what should happen next.

This Is Not Automation

This distinction is important.

Automation means: "Do these steps faster."

What I built is: A decision-aware workflow.

The AI validates README consistency, checks semantic versioning, verifies branch state, creates tags, triggers GitHub Actions, publishes to NuGet — and explains why at each step.

I call this pattern Decision/CD: where the pipeline doesn't just execute, but decides.

The Workflow I Designed

Here's the actual release flow I use for my OSS project:

Local → RC → Verify → GO/NO-GO → Tag → Stable → Publish

flowchart TD
  A["Local prep<br/>build/test + docs"] --> B["Publish RC<br/>(GitHub Packages)"]
  B --> C["Download RC & verify<br/>(restore + smoke test)"]
  C --> D["GO decision<br/>(coordinator)"]
  D --> E["Lock commit hash"]
  E --> F["Publish stable<br/>(nuget.org)"]
  F --> G["Aftercare<br/>docs + announcements"]

Each stage has conditions, evidence requirements, and clear ownership.

Roles: Who Does What

Here's how I divided responsibilities:

Role	Responsibility
Release coordinator	GO/NO-GO judgment, final checklist
Implementor	Build, API consistency, package verification
Physical test owner	Run tests, record evidence, document conditions
Env/Infra owner	Docker, Kafka, environment troubleshooting
Quality review	README, examples, documentation review
Evidence & log	Maintain diff logs, prevent gaps

In my workflow, these roles are assigned to AI agents. The human (me) only handles the coordinator role — specifically, the GO/NO-GO decision.

Decision Gates: Where Human Judgment Lives

The GO/NO-GO decision requires:

✅ Unit tests green
✅ Physical tests green (with evidence)
✅ Diff log recorded (if changes exist)
✅ README works as user documentation

If all conditions are met, I say "GO." The AI handles everything after that.

The CI/CD That Makes It Work

Two simple GitHub Actions workflows power this:

RC Publish (on release/** branch push):

on:
  push:
    branches:
      - "release/**"

This workflow builds, tests, packs with -rcN suffix, and pushes to GitHub Packages.

Stable Publish (on v*.*.* tag push):

on:
  push:
    tags:
      - "v*.*.*"

This workflow validates SemVer, runs tests, packs the stable version, and pushes to nuget.org.

That's it. The AI creates the branch, verifies conditions, creates the tag — and the pipelines do the rest.

A Real Interaction

Here's what an actual release session looks like:

Human: Check the README.

AI:

Conclusion: The English in README.md is clear and accurate.

Reasoning:

Meaning is clear and concise

Technically accurate

Consistent with other documentation

Suggestion: Let me know if you need consistency checks on other READMEs.

Human: Commit and push.

AI:

Conclusion: Commit and push completed.

Reasoning:

Commit: docs: translate src README

Changed: README.md (English translation)

release/1.2.0 pushed to remote

Suggestion: Let me know if other READMEs need English consistency checks.

Human: Merge to main and release to NuGet.

AI:

Conclusion: Merged release/1.2.0 to main. NuGet release requires a tag.

Reasoning:

main now includes latest from release/1.2.0

Release is triggered by v*.*.* tag push (per nuget-publish.yml)

VersionPrefix in Directory.Build.props is 1.2.0

Suggestion: Ready to create and push v1.2.0 tag?
(If OK, I'll run git tag v1.2.0 → git push origin v1.2.0. Please confirm NUGET_API_KEY is set in GitHub Secrets.)

Human: Create and push v1.2.0 tag.

AI:

Conclusion: Created and pushed v1.2.0 tag.

Reasoning:

git tag v1.2.0 executed

git push origin v1.2.0 executed

Matches NuGet publish workflow trigger conditions

Suggestion: GitHub Actions workflow "Publish stable to nuget.org" should now be running. Let me know if you need completion confirmation.

The pattern:

Human	AI
4 short commands	4 structured reports
"Check" / "Push" / "Merge" / "Tag"	Conclusion → Reasoning → Suggestion
No manual verification	Decision gate before irreversible action

The entire release — from verification to NuGet publish — took 4 human messages.

Why Most AI Workflows Fail

Most AI usage in development looks like this:

❌ "Write code for me"
❌ "Fix this bug"
❌ "Optimize this function"

That's not a workflow. That's outsourcing.

There's no structure. No decision gates. No evidence requirements. No ownership model.

When you outsource without structure, you get unpredictable results.

The Division of Labor

Here's how I think about human-AI collaboration:

Human	AI
Intent	Execution
Judgment	Procedure
Responsibility	Operations
Declaration	Action

The human decides what and whether. The AI handles how and when.

This separation is what makes the workflow operable.

What Makes a Workflow "AI-Operable"

A workflow is AI-operable when:

Stages are explicit — The AI knows where it is in the process
Conditions are verifiable — The AI can check them programmatically
Evidence is defined — The AI knows what proves success
Decision points are marked — The AI knows when to stop and ask
Failure modes are specified — The AI knows what to do when things break

If your workflow has these properties, an AI can operate it. If not, you're just hoping for the best.

Final Thought

CI/CD automates pipelines. It does not automate decisions.

That's the layer I built.

I didn't make my workflow smarter. I made it operable by AI.

And that changed everything.

This is part of my "Beyond Prompt Engineering" series, where I explore human-AI collaboration patterns that go beyond optimizing prompts. The workflow shown in this article is from Kafka.Context, an OSS project I develop entirely through human-AI collaboration.

The Hidden Trust Problem in AI-Generated Documentation

synthaicode — Wed, 14 Jan 2026 14:00:00 +0000

The first time AI generated documentation for my project, it looked perfect.

Clear structure. Confident tone. Professional language.

That was exactly the problem.

A week later, when I tried to review it, I realized I couldn’t answer a basic question:

Which parts of this document came from my requirements, and which parts did the AI make up?

Everything was written with equal confidence. There was no way to tell where I should trust the content—and where I needed to verify it.

Why This Is a Problem You Don’t Notice at First

When AI creates documentation, it doesn’t distinguish between:

facts you explicitly provided
information inferred from existing documents
assumptions made to fill gaps
general industry conventions

All of them look the same on the page.

At first, that feels convenient.

Later, it becomes dangerous.

Because when you revisit the document—or when someone else relies on it—you can no longer tell what is actually true versus what merely sounds reasonable.

The Problem After Import

In my previous article, I discussed how to safely import legacy documents using question-driven integration. That approach works well at the entry point.

But I ran into a new problem after the import.

Even with careful integration, AI-generated documents still mix different kinds of information without distinction.

Consider a typical API design section:

The API uses REST architecture with JSON responses.
Authentication requires Bearer tokens.
Rate limiting is set to 100 requests per minute.
Error responses follow RFC 7807 format.

Which of these came from my requirements?

Which did the AI infer?

Which are just defaults pulled from general knowledge?

I couldn’t tell.

And neither could the AI when it referenced this document later.

The Solution: Source Attribution

The fix was simple in concept, but powerful in practice:

Require AI to tag every statement with its source.

Each claim must declare where it came from.

Tag	Meaning	Trust Level
`[explicit]`	Directly provided by the user	High — use as-is
`[inferred]`	Derived from existing documents	Medium — verify
`[assumed]`	Placeholder due to missing info	Low — needs input
`[general]`	Filled from general knowledge	Low — override if needed

The same section rewritten:

 [explicit] The API uses REST architecture with JSON responses.
 [inferred] Authentication requires Bearer tokens.
  └─ "All endpoints require authentication" (REQUIREMENTS.md L.23)
 [assumed] Rate limiting is set to 100 requests per minute.
 [general] Error responses follow RFC 7807 format.

Now the review effort is obvious.

I know exactly where to focus.

Why Inferences Must Include Citations

The [inferred] tag turned out to be the most dangerous one.

AI is very good at post-hoc rationalization.

It can reach a conclusion first, then search for text that sounds supportive.

So I added a rule:

Every inferred statement must include a verbatim quotation from its source.

Example:

[inferred] Retry policy allows 3 attempts
└─ "External API calls should retry up to 3 times" (API_DESIGN.md L.28)

The quote must appear exactly in the source.

If the quote doesn’t support the conclusion, the problem is immediately visible.

Without the quote, I’d have to hunt through documents myself.

With it, verification takes seconds.

Where Source Attribution Is Required

Not everything needs tags. The rule is simple:

Tag documents that others will rely on as truth.

Document Type	Tags Required	Verification Method
Work logs	No	Point-in-time record
Design specs	Yes	Human review
README / Guides	Yes	Human review
Test specs	Yes	Cross-reference
Source code	No	Executable tests

Source code already has a verification mechanism: tests.

Documentation doesn’t.

Source tags provide the missing verification metadata.

Code comments are excluded as well. Embedding design rationale in comments creates maintenance debt—comments rot silently when documents change.

The Terminology Drift Problem

Source attribution alone breaks down when terminology drifts.

# API_DESIGN.md
[explicit] Retry policy allows 3 attempts
# SERVICE_SPEC.md
[inferred] Re-execution strategy permits 3 tries
# TEST_SPEC.md
[inferred] Fault recovery mechanism uses 3 retries

Same concept. Three names.

Now grep fails.

Impact analysis fails.

Humans lose trust.

Conversation-Based Terminology Unification

The solution wasn’t a static glossary—that’s just another document to forget.

Instead, terminology is unified during conversation.

Human: "The re-execution count should increase to 5"

AI: "You mentioned 're-execution'. Is this the same as
'retry policy (#retry-policy)' in existing docs?"

Human: "Yes."

AI: "Understood. Updating retry policy to 5 attempts."

Drift is caught at the point of entry, not after the damage spreads.

The Multi-User Reality Check

This works well for single-user workflows.

It breaks with multiple users.

Different people, different sessions, different terms—parallel truths emerge.

This is the limit of conversational unification.

Solving it requires shared infrastructure: synchronized glossaries, versioned terminology, or serialized workflows.

That is a different class of problem.

The Pragmatic Boundary

Don’t retrofit this onto everything.

New projects: AI involved from day one → tags and terminology stay clean
Legacy systems: use question-driven integration, then enforce rules going forward

Draw a boundary.

New work follows the protocol.

Legacy stays untouched until it’s modified.

Why This Matters

Source attribution doesn’t make AI perfect.

It doesn’t prevent mistakes.

What it does is make mistakes visible.

When you can see where AI was certain versus where it guessed, you know where to apply human judgment. That visibility is the foundation of trust in AI-collaborative development.

This article is part of the Beyond Prompt Engineering series, exploring systematic—not accidental—ways to work with AI.