The models got dramatically better. The output still isn't shippable. Here's what's actually missing and the twelve-skill system I built to fix it.
I want to start with an uncomfortable observation.
The coding models available today are extraordinary. They hold a codebase in their head, reason across services, and write better code than most of what's already in your repo. And yet, if you've used one on real work, not a demo, not a weekend project, but the codebase your team ships from, you know the feeling of reading 300 lines of confident, well-formatted output and thinking: I have to throw all of this away.
That gap is the interesting problem. And I'm convinced it isn't a reasoning problem.
The bottleneck moved
Think about the best engineer you've worked with. Now imagine they joined your team and, on day one, started writing code before anyone told them the requirements, without asking what database you use, without reading how the existing services are structured, and without running the test suite before saying they were finished.
Talented, yes. But that's not how good work gets done, and it has nothing to do with intelligence. It's process.
Software engineering is not the act of producing code it's the discipline surrounding it: settling intent before building, sequencing work so the risky parts land first, proving things work rather than asserting it, and leaving a trail someone else can follow.
Agents skip all of that by default. Not because they can't do it, but because nobody asked them to.
The four failure modes
Working with agents on production code, the same four failures kept showing up. Every one of them is a process failure, not a capability failure.
1. It codes before intent is settled. You write a paragraph; it writes an implementation. Every unstated assumption (the database, the auth model, where business logic lives) gets silently decided by the agent, and you discover the wrong ones after the code exists. The cheapest moment to kill a bad assumption is while it's still one sentence in a spec. Instead we kill it after an hour of generated code.
2. It forgets everything when the session ends. Close the laptop, come back tomorrow, and the context is gone. Decisions you made, questions you answered, constraints you explained: all of it lived in a chat window that no longer exists. So you re-explain, and hope you remember all of it.
3. It says "done" without proof. This one costs the most trust. The agent reports success; you run the tests; three fail. It didn't lie. it simply never checked. "I've implemented the feature" and "I ran the suite and read the output" are different claims, and agents blur them constantly.
4. It writes in its own accent. Your codebase uses the repository pattern and validates at the route boundary. The agent knows twelve valid architectures and picks one. The result is technically correct and fails review, because it reads like a different codebase spliced into yours.
What discipline actually looks like
I built Itqan ("إتقان" Arabic for mastery of a craft) around four rules that each answer one of those failures. They're worth stating plainly, because they're the whole idea:
Rule 1: Approval gates, written to disk
No implementation begins until you approve the spec. Not a "yes" in a chat message the model may or may not carry forward a flag written to a file on disk.
That distinction is the single most important design decision in the system. A chat-level yes lives in a context window; it decays, gets truncated, or gets confabulated. A flag on disk means a resumed session cannot pretend you consented to something you never saw. The gate holds a week later, on a different machine, in a different session.
Rule 2: Evidence, not assertion
"Done" requires artifacts. The tests were run and the output was read. The bug was reproduced before it was fixed, and the reproduction is now a pinned failing test that goes green. For a production issue, the close-out isn't "fixed". it's re-running the original query and showing the rate at zero.
Anything that can't be shown isn't claimed.
Rule 3: A written trace
Every clarifying question and its answer is saved in a structured file. Every task gets a close-out summary. Every feature gets a changelog entry explaining why, not just what.
Three months later, when someone asks why the schema looks like that, the answer is in a file, not in a chat log nobody can search.
Rule 4: Your conventions, detected and followed
Before asking you anything, the system scans the repo and shows you its read: stack, test tooling, patterns it found, integrations. You correct anything wrong in a word. That gets written down once and followed from then on.
New code that looks like your code passes review. New code in the agent's house style does not.
How it's organized
Twelve skills: one orchestrator, six lifecycle phases, five specialists.
You only ever need to know one of them. engineer is the entry point. it detects where you are, decides how much ceremony the task deserves, and routes to the right skill itself. Small isolated fix? It skips spec and plan entirely and goes straight to a test-first change. Big feature? Full pipeline, both gates.
The six phases run the flow: define (idea → approved spec, with schema and API contracts) → blueprint (spec → dependency-sorted, risk-first task plan) → construct (tests first, in your codebase's style) → verify (run it, read the output, root-cause failures) → inspect (five-axis review) → release (rollback plan and an explicit GO/NO-GO).
The five specialists sit outside the flow, for when you need them: discover (what to build next, with citations), design (UI/UX), harden (security), assess (whole-app health), learn (onboarding and learning paths).
One structural detail worth calling out: inspect, harden, and assess are read-only. They report findings and route fixes elsewhere; they don't touch the code they're judging. A reviewer that can edit what it reviews will quietly rewrite your branch and call it feedback.
The part that surprised me
The gates were supposed to be a safety feature. They turned out to be a speed feature.
I expected approval steps to slow everything down. In practice, the time spent settling a spec is a fraction of the time previously spent discovering after implementation that the agent assumed the wrong thing. The rewrite tax is the real cost of AI-assisted development, and gates are how you stop paying it.
The honest limits
This is more ceremony than "hey, build me a login page." For a throwaway script, the ceremony isn't worth it, and the system will tell you so triage skips the pipeline for small isolated changes.
It also won't understand a legacy system that you don't understand either. It'll surface what it found and state what it couldn't verify more useful than confident nonsense, less useful than the engineer who's been maintaining it for five years.
And on a large under-specified system, it deliberately slows down and asks more questions rather than making a big change on a shaky read. If what you want above all is speed, that will annoy you.
That's the trade I made on purpose. I'd rather be asked than surprised.
What's next in this series
This piece is the argument. The rest of the series is the practice one article per skill, each one applying it to a real repository, showing the actual output, comparing what I expected against what came out, and being specific about when not to use it.
Next: engineer one command, the whole lifecycle, and the resume that survives a closed laptop.
Itqan is open source, MIT licensed, and works with any AI code platform.
Docs and install: https://saleh-alhaddad.github.io/itqan-engineering
Repo: https://github.com/saleh-alhaddad/itqan-engineering
Top comments (0)