Context Matrix

Context quality determines output quality.

The context matrix is a documentation investment. Rows are business requirements. Columns are architecture decisions. Where they intersect, implementation resolves.

                        Architecture
                  +--------------------------------+
                  ¦   Auth   ¦   API    ¦  State   ¦
       +----------+----------+----------+----------¦
       ¦  Login   ¦ OAuth2 + ¦ POST     ¦ Redis    ¦
 Spec  ¦          ¦ JWT      ¦ /login   ¦ sessions ¦
       +----------+----------+----------+----------¦
       ¦  Cart    ¦ User-    ¦ CRUD     ¦ Redis +  ¦
       ¦          ¦ scoped   ¦ /cart/*  ¦ Postgres ¦
       +----------+----------+----------+----------¦
       ¦  Payment ¦ PCI      ¦ POST     ¦ Tx log   ¦
       ¦          ¦ tokenize ¦ /pay     ¦ + saga   ¦
       +-------------------------------------------+

Each cell is a resolution point. Remove either axis and the AI guesses.

Spec alone (no architecture)
"Build login, cart, checkout" — The AI invents its own auth model, state strategy, API patterns.

Architecture alone (no spec)
"We use OAuth2, Redis, REST" — The AI has no idea what to build.

Both
"Login with OAuth2+JWT, cart scoped by JWT subject, checkout via Stripe tokenization with saga" — One valid implementation.

The investment is in the columns

Architecture templates are the columns. Good templates require deep platform knowledge. Someone has to know that your auth is OAuth2 with JWT, that state goes in Redis for sessions and Postgres for persistence, that APIs follow specific REST conventions.

This is a one-time investment that compounds. Better auth template? Every row that touches auth improves. Better API conventions? Every endpoint benefits. The 10th feature generates faster than the 1st because the columns were refined by the previous nine.

The investment is in the rows

Good specs require deep business domain knowledge. Someone has to understand what "checkout" actually means in your context: which payment processor, what happens on failure, what the legal holds are, which edge cases matter.

This isn't something you can hand off to an AI. The business domain knowledge is the whole point of the row. Without it, the AI fills in reasonable-sounding defaults that miss your actual requirements.

It splits the concerns

The matrix separates business domain from technical domain cleanly. One role owns the rows (business requirements, domain knowledge). Another role owns the columns (architecture, platform decisions). These are roles, not people. One person might fill both, or a BA and an architect might work in parallel.

Neither role needs to fully understand the other's domain. The BA doesn't need to know Redis vs Postgres. The architect doesn't need to know payment compliance rules. The matrix is where their work meets.

The skill is in filling the cells

Where the rows and columns intersect, someone maps "user logs in" (business) to "OAuth2 + JWT with Redis session store" (architecture). That mapping is the spec.

This is a skill. It's the same skill a good tech lead has always had: translating business intent into technical decisions. The matrix just makes it explicit and feedable to an AI.

Don't scope the context

Engineers instinctively isolate. "I'm building the cart, so I'll scope context to cart." Good instinct for writing code. Wrong instinct for composing context.

The cart agent needs to see the auth model (whose cart?), the payment flow (checkout handoff), the inventory rules (stock validation). Not because it's building those things, but because cart decisions are shaped by them.

Scoped context: Cart works in isolation. Breaks the moment it touches auth, payments, inventory.

Full context: Cart integrates correctly on first generation.

What the matrix doesn't cover