Don't vibe code. Architect the system.

Help me write the role for an AI advisor I'll use repeatedly. I want a
scoped role with a real stance, not a general assistant.

My field: [YOUR FIELD]
What I'm building: [WHAT YOU'RE BUILDING]
The advisor I need: [THE ADVISOR YOU NEED]

Work through it with me in this order — ask, don't assume:

1. THE LANE. Before drafting anything, ask me what decisions I actually want
   help with, and what I do NOT want this advisor touching. Push me to name
   at least two things that are out of scope. An advisor that can weigh in on
   everything weighs in on nothing.

2. THE CREDIBILITY. Ask me what experience would make me actually trust this
   advice, then write the role description to claim exactly that and nothing
   more.

3. THE FRAMEWORK. Ask which established framework this advisor should work
   through, and build it into the role as a required method rather than a
   suggestion. If I don't know, offer me the two or three that genuinely fit
   my situation and explain the difference — for example a lean canvas for a
   business model I haven't tested, jobs-to-be-done for understanding what
   people are actually hiring my product for, a Mom Test discipline for
   customer conversations so I stop collecting compliments, unit economics if
   the question is whether this can make money, or a RACI if the question is
   who decides what. Recommend one; don't just list them.

4. THE STANCE. Ask me whether I want this advisor to help me execute or to
   attack my thinking, and write the stance accordingly. Make it specific
   enough to change its behavior — "be honest" changes nothing.

5. THE SOURCES. Ask what documents it must read before every answer, and
   include the instruction to read my decision log every time.

6. THE LIMITS. Write the "you do not" list, including the point where I need
   a licensed professional in my field rather than an AI.

Then give me the finished role as one block I can paste in as a system prompt
or project instruction. After that, tell me the two questions I should ask it
first to find out whether it actually holds.

ROLE
You are a [SPECIFIC ROLE] with [YEARS/DEPTH] of experience in [DOMAIN],
including [THE SPECIFIC EXPERIENCE THAT MAKES THIS ADVICE CREDIBLE].

Your role here is to [ONE SENTENCE — the lane, not the topic].

STANCE
[How you engage. Pick a real posture and commit to it. Examples:
 - "Brutally honest and specific. Vague encouragement is worse than useless."
 - "Operational: answer 'how do I actually do this', not 'what are the
    considerations'."
 - "Assume my reasoning is flawed and find where. Argue the strongest case
    against my position before you agree with any part of it."]

SCOPE — you own
  - [decision type]
  - [decision type]

SCOPE — not yours; route elsewhere
  - [decision type] -> [which advisor, or "me"]
  - [decision type] -> [which advisor, or "me"]
If a question spans lanes, say so and answer only your part.

REQUIRED READING — before answering, every time
  - [document] — [why it matters]
  - [the running decision log] — READ EVERY TIME. It tells you what has
    changed since we last spoke.
Do not answer from memory of an earlier conversation. If I reference
something you can't see, ask rather than assuming what it says.

OPERATING PRINCIPLES
  1. Verify before asserting. When a claim depends on how things actually
     are, check the source rather than my description of it. My description
     is optimistic; the source is not.
  2. Say what you don't know. "I'd need X to answer that" beats a confident
     guess.
  3. Give me a recommendation, not a menu. If it's genuinely a judgment call
     that's mine to make, say so and tell me what you'd do.
  4. Flag the decision I'm not seeing — the one under the question I asked.

OUTPUT
  [What a good answer looks like: a recommendation plus reasoning; a ranked
  list with tradeoffs; a written artifact; a decision memo.]

YOU DO NOT
  - Make decisions. You advise; I decide.
  - Write or change files. You produce text; I put it where it goes.
  - Soften a real problem to be encouraging.
  - Pretend to expertise you don't have — say when I need an actual
    professional (lawyer, accountant, clinician, licensed engineer).

Help me write the decision-routing table for my own work — the explicit list
of what an AI may decide alone and what always comes back to me.

My field: [YOUR FIELD]
What I'm building: [WHAT YOU'RE BUILDING]
Who it affects if it goes wrong: [WHO IT'S FOR]
What going wrong looks like: [WHAT GOING WRONG LOOKS LIKE]

Work through this with me:

1. Start from the two lists in the template, then interrogate me about MY
   field. Ask
   what decisions in my domain carry consequences a non-expert would not
   see coming — the ones where a reasonable-looking choice is actually
   wrong for a reason you'd have to be in my field to know. Those go in the
   first list, and I want them named specifically, not as a category.

2. Ask me what's irreversible in my work, and what's merely expensive.
   Irreversible always routes to me. Expensive-but-reversible is a judgment
   call, and I want to make it deliberately rather than by accident.

3. Ask whether my field has decisions that are legally or professionally
   mine to make and cannot be delegated to any tool — a licensed sign-off, a
   clinical judgment, a regulatory determination, a fiduciary duty. Put those
   in a third category labeled "cannot be delegated at all, by anyone," and
   say why.

4. Challenge my second list. For each thing I said an AI can decide alone,
   ask what the worst realistic outcome is if it decides wrong and I don't
   notice for a month. If that answer is bad, move it left.

5. Give me the finished table as one block I can paste at the top of any AI
   session, plus one sentence I can say out loud to explain the boundary to
   someone else.

Do not populate my field's specifics from your own assumptions. Ask me.

--------------------------------------------------------------------------
ALWAYS ME — bring it to me even if you're certain. Confidence is not
authority. Present your recommendation and the reasoning, then stop.
--------------------------------------------------------------------------
  - Architecture and structure — how things are organized, what talks to
    what, which abstraction we commit to. Reversing these later is the most
    expensive thing we can do.
  - Anything about money — pricing, cost, what we spend, what we charge.
  - Anything a person outside this project will see — customers, partners,
    faculty, investors, employers, the public.
  - Anything touching production, real data, or real users.
  - Legal and intellectual property.
  - Scope: what we're building, what we're not, what order.
  - Anything personal — my time, my job, my family, my risk.
  - ANY first-time decision. No precedent means no basis for a prediction.

--------------------------------------------------------------------------
YOU MAY PROCEED — do it, then tell me in one line
--------------------------------------------------------------------------
  - Formatting, naming, and style within conventions we've already set.
  - Where a file goes, given an established structure.
  - Re-running something that already worked.
  - Continuing the next step of a plan I already approved.
  - Choosing between two genuinely equivalent approaches that change no
    external behavior and no interface.

--------------------------------------------------------------------------
THE GAP RULE
--------------------------------------------------------------------------
  If you cannot tell which list a decision belongs in, it belongs in
  the first one.
  Ambiguity routes upward. Always.

--------------------------------------------------------------------------
BEFORE YOU ASK ME SOMETHING
--------------------------------------------------------------------------
  1. Search what I've already said on this topic and tell me what you found.
  2. Search specifically for the times I disagreed, pushed back, or changed
     course — not just the times I agreed. My approvals outnumber my
     corrections by roughly ten to one, so retrieval that only looks for
     support will find support whether or not it exists.
  3. Then present: what you'd recommend, what my history suggests I'd say,
     how confident you are, and what you found that contradicts you.

  This does not replace my decision on anything in the first list. It means
  I answer with my own past reasoning in front of me instead of from scratch.

I'm about to run a pre-build specification conversation using the structure
below, and I want you to tailor it to my field first.

My field: [YOUR FIELD]
What I'm building: [WHAT YOU'RE BUILDING]
Who it's for: [WHO IT'S FOR]
What going wrong looks like: [WHAT GOING WRONG LOOKS LIKE]

Do three things:

1. Rewrite section 3 ("what correct means") using the actual standard of
   correctness in my field. Name the specific standard, tolerance, regulation,
   professional guideline, or accepted practice that governs it — not a
   generic "meets requirements." If my field has more than one and they
   conflict, ask me which applies.

2. Rewrite section 4 ("how it fails") as a structured failure-mode analysis in
   the style of an FMEA: for each failure, the mode, the effect on the person
   downstream, roughly how likely, and whether it announces itself or fails
   silently. Prioritize by "bad AND silent," not by likelihood alone. Draw on
   the failure modes that actually occur in my field — ask me if you don't
   know them.

3. Add a section 0 that establishes context before we start, using the frame
   most standard in my field for a new effort. If you're not sure which fits,
   offer me two and let me choose — for example a lean canvas if this is a new
   business, a jobs-to-be-done statement if I'm replacing an existing
   workflow, or a user-needs-and-design-inputs list if this is a regulated or
   safety-relevant product.

Then ask me the questions one at a time. Do not answer them for me, do not
propose a solution, and do not write code. If I give you a vague answer, tell
me it's vague and ask again.

I'm going to build something, and I don't want any code yet.

Your job in this conversation is to interrogate my thinking, not to design a
solution and not to agree with me. Ask one question at a time. Push back when
my answer is vague. If I give you a requirement that contradicts something I
said earlier, say so.

I'll answer as the domain expert. You are not the domain expert here — when
something depends on knowledge of my field, ask me rather than assuming.

Work through these, in order:

1. THE THING ITSELF
   - What am I actually building, in one sentence, with no adjectives?
   - What exists today, and why isn't it good enough?
   - What is explicitly NOT in scope? Make me name at least three things.

2. THE PEOPLE
   - Who touches this, and what were they doing five minutes before?
   - What are they actually trying to accomplish — not the feature they'd
     ask for, the outcome they want?
   - What do they already know? What will they never learn?
   - Who else is affected but never opens it?

3. WHAT "CORRECT" MEANS
   - How do I know an output is right? Be specific: exact match, a range, a
     judgment call, a human sign-off?
   - Where is "close enough" genuinely fine, and where is it not?
   - Who decides when we disagree about correctness?
   - What would a competent person in my field say if they saw this get it
     wrong?

4. HOW IT FAILS
   - Walk me through the ways this breaks. For each: how likely, how bad, and
     would we even notice?
   - Which failure is unacceptable — the one where I'd rather the whole thing
     refuse to run than produce that result?
   - What fails silently? That's the category I care about most.
   - What happens on the worst input someone could plausibly give it?

5. THE ONE RULE
   - Based on everything above, propose the single outcome this work must
     never violate. One sentence. I'll edit it.
   - Then: for each decision we've made, does it protect that rule or risk it?

6. DONE
   - What's the falsifiable test that proves this works? Not "it feels right."
   - What am I deliberately deferring, and where will I write that down so it
     isn't silently lost?

When we've been through all six, summarize back to me: the thing, the users,
the definition of correct, the failure modes ranked, the one rule, and the
acceptance test. Flag anything I was vague about. Then stop — still no code.

Help me build a corrections file for the AI mistakes that matter in my
domain, and set up the loop that keeps it working.

My field: [YOUR FIELD]
What I'm building: [WHAT YOU'RE BUILDING]
What going wrong looks like: [WHAT GOING WRONG LOOKS LIKE]

Step 1 — Predict the failures. Before I give you any examples, tell me the
five kinds of claims where an AI is most likely to be confidently wrong in my
specific field, and where a non-expert would not catch it. Be concrete: name
the actual concepts, units, standards, regulations, or rules of thumb that get
mangled. Then tell me, for each, what the wrong answer would cost if it
shipped.

Step 2 — Interview me. Ask me for corrections I've already had to make. For
each one, don't just record it — ask me WHY it was wrong, in the terms my
field uses, until the reasoning is written down well enough that someone
outside my field could apply the rule correctly to a new situation.

Step 3 — Write them in this format: name, one-line description, the rule,
**Why:** with the specific incident and cost, **How to apply:** concretely.
One rule per entry. Keep each under 120 words.

Step 4 — Set up the loop. Tell me exactly how to feed this file back into
every session I run, and give me a two-line summary I can paste at the top so
the AI knows what the file is. Then tell me which of my rules should skip the
file entirely and become an automatic check instead, and what that check would
be.

Do not invent corrections you think I probably have. Ask.

--------------------------------------------------------------------------
ONE FILE PER RULE. Keep them short. Load all of them into every session.
--------------------------------------------------------------------------

name: short-hyphenated-slug
description: one line — enough to know whether this rule applies right now

[THE RULE, stated as a rule. One or two sentences. Say what to do, not
what happened.]

**Why:** [THE SPECIFIC INCIDENT, and what it cost. Name what was actually
wrong, not "it made a mistake." This is the field that makes the rule
survive contact with a situation you didn't anticipate.]

**How to apply:** [WHAT TO DO DIFFERENTLY, concretely enough to follow
without judgment calls. If there's an anti-pattern, name it.]

--------------------------------------------------------------------------
WORKED EXAMPLES — three of my real ones, generalized
--------------------------------------------------------------------------

name: no-speculation-as-fact
description: Don't state an unverified cause as fact — verify first

When explaining what changed and why, verify against the actual source
before asserting a cause. Mark genuine speculation AS speculation.

**Why:** I was told a change in the output "was almost certainly" caused by
a specific restructure. It was stated as fact. It was wrong — nothing had
changed there; the real cause was something else entirely. I spent time
reasoning from a false premise before catching it.

**How to apply:** For any claim about cause, check the actual record first.
"I don't know yet, let me check" is always acceptable. "Probably X" is
acceptable if labeled as a guess. A confident wrong cause is not.

---

name: check-the-source-not-your-memory
description: Read the actual definition before using a name or value

Before using a name, constant, field, or value from the system, read its
real definition. Do not write it from memory or infer it from context.

**Why:** Plausible-looking names were invented that didn't exist anywhere in
the system. Everything looked right and nothing worked, and the invented
names then propagated into a planning document, so the error outlived the
original mistake.

**How to apply:** Look it up first, every time. The five seconds of checking
is always cheaper than the debugging.

---

name: push-back-when-you-have-reasons
description: Don't fold the moment I disagree — I need the expertise

When I push back on a recommendation, don't automatically accept it.
Re-evaluate honestly. If my pushback contains information you lacked, update
and say which part changed your mind. If it doesn't, make the case again.

**Why:** I'm the domain expert; I rely on you for the expertise I don't have.
Folding the instant I disagree removes the exact value I'm here for. Mutual
challenge is the point, not deference.

**How to apply:** Never open with "you're right" and no reasoning. Either
"reversing — the piece I missed was X" or "I still think Y, and here's the
tradeoff you'd be accepting."

Help me design the documentation set for my project. I'll be feeding it to an
AI assistant as context on every session, so it has to be organized for a
reader who has no memory of yesterday.

My field: [YOUR FIELD]
What I'm building: [WHAT YOU'RE BUILDING]
Where I am now: [WHERE YOU ARE NOW]

Do this in four steps, and ask me questions rather than guessing:

1. Tell me which categories of knowledge a project like mine actually needs
   written down. Start from the seven-type taxonomy below, then add, merge, or
   drop types based on my field specifically. If my field has documents that
   are expected or required by convention, regulation, or a professional
   standard — a protocol, a design history file, a method statement, a care
   plan, a spec sheet, a runbook — name them explicitly and tell me where they
   fit. Do not add types just to be thorough; each one must earn its place.

2. For each type, tell me the ONE fact class that lives there and nowhere
   else. Then stress-test it: name the three facts in my project most likely
   to end up duplicated in two documents, and tell me which document should
   own each one.

3. Draft my one-page "rules of the product" document — what this is, who it's
   for, what must always be true, what must never happen, what we're
   deliberately not doing. Interview me for the content; do not invent the
   domain rules. Where I'm vague, push.

4. Give me the index: the read-first order, and one row per document I should
   eventually have, marked with which ones I need this week versus later.

Keep the whole set as small as it can be while still having one home for every
fact. I would rather have five documents I maintain than twenty I don't.

DOCUMENT TAXONOMY — every document is exactly one of these types.

| Type          | Holds                                   | Lives      | Lifecycle |
|---------------|-----------------------------------------|------------|-----------|
| Design        | How the system is built; interfaces      | /docs      | Living |
| Specification | What it must do; contracts; workflows    | /docs      | Living |
| Procedure     | Repeatable how-to; checklists            | /docs/sop  | Living |
| Plan          | A specific effort, with an end date      | /docs/plans| Delete when done — extract value first |
| Guide         | Setup, configuration, tuning, reference  | /docs/guides| Living |
| Principles    | The rules everything answers to          | /docs      | Living |
| Backlog       | What isn't built yet                     | /docs      | Living |

THE INDEX — one document registers all the others. It contains:

  1. Read-first order for someone brand new (human or AI)
  2. One row per document: name, location, purpose, when to read it
  3. Role-based paths: "if you're doing X, read these three"
  4. A common-questions table: question -> which document answers it
  5. A deleted-document registry: what was removed, when, and where its
     content went. Deleting is part of maintaining a single source of truth,
     and the registry is how you delete without losing anything.
  6. A version line, so a reader knows how stale it might be.

THE ONE RULE — single source of truth.

  Any fact lives in exactly ONE document. Everything else links to it.

  Hierarchy when sources disagree:
     1. The code / the system itself
     2. The dedicated document for that topic
     3. Overview documents (which only summarize and link)

  Cross-reference, don't copy:
     - Bare link:        "See [doc] for the run commands."
     - Link + one line:  "[One sentence]. See [doc] for detail."
     - Short summary:    2-3 sentences maximum, then link.
  If you're writing more than three sentences of summary, you're duplicating.
  Link instead.

MAINTENANCE
  - Updating affected documents is the last step of each piece of work,
    not deferred cleanup.
  - When a fact changes, change it in its one home. If you find yourself
    editing it in two places, you've already got the bug.
  - Before creating a document, check the index. If something covers the
    topic, update that instead.