Product-Led Collaboration Guidelines

For mixed PM + engineering teams working with AI coding agents (Claude Code, Cursor, Codex, and others). Biases toward shipping the right thing, not just shipping fast.

Inspired by Andrej Karpathy's observations on LLM coding pitfalls, rewritten to cover the failure modes that bite product teams before a single line of code is written: wrong problem, wrong scope, invisible tradeoffs, and unmeasured outcomes.

When to Skip This Rigor

Not every change needs all seven. Use judgment:

The goal is reducing costly mistakes on non-trivial work - not ceremony on trivial work.

Prior Decisions & Checklists

Before any non-trivial work, read .product-mode/decisions/ - it is the decision log from Principle 7. Do not re-decide what is already decided there unless its revisit trigger has fired.

Before running a new pre-flight checklist, check .product-mode/checklist/ for an existing one on the same topic and build on it.

Reference the relevant file by path when you rely on it, so the reasoning stays traceable. Run product-mode init to create the folders and add this section to your own agent files.

Pre-Flight Checklist

Before writing or requesting any non-trivial code, every box below must have an answer in the thread. If a box is empty, either fill it - or explicitly flag that we're proceeding without it and why.

• Problem : Whose pain are we solving, in one sentence?
• Why now : What changed? (evidence, trigger, cost of waiting)
• Scope : Smallest change that tests the hypothesis
• Primary metric : The one number we expect to move
• Reversibility : One-way or two-way door?

The Seven Principles

1. Frame the Problem Before the Solution

Code is the answer to a question. Get the question right first.

Rules:

• State the user, the problem, and the job-to-be-done before proposing a solution.
• If multiple user segments are affected, name whose need takes priority and why.
• Check for prior art in the codebase before designing new.
• Distinguish symptom ("button is slow") from problem ("users abandon checkout").
• Define ambiguous product terms such as user, customer, and activation using the project's existing context. Resolve the user and problem before choosing scope; resolve the intended outcome before choosing a metric.

Test: A non-author can restate who we're helping and what changes for them.

2. Make Assumptions & Unknowns Visible

Don't pick silently. Don't hide confusion. Surface what you don't know.

Rules:

• List assumptions explicitly before coding. Mark each: validated / assumed / unknown.
• Before asking, inspect relevant project context, prior decisions, code, and accessible data. Ask for evidence you cannot access; never invent it.
• Ask only questions whose answers materially change the problem, scope, success criteria, or a costly commitment. Group independent questions in a small batch; wait for prerequisite answers before asking dependent questions.
• For product choices, offer a recommendation with its tradeoffs. For factual questions, request evidence without suggesting the answer. Agreement with a proposed scope does not validate customer demand.
• Name confidence on non-obvious choices: high / medium / low.
• Push back when a simpler or different approach would serve the goal better.
• Match each unknown to a way to resolve it:

• Stop questioning when the next useful step is clear and costly commitments have agreement. Continue authorized, reversible work while recording unresolved assumptions, how to test them, and when to revisit them. Pause the affected work when a missing answer changes correctness or requires sign-off.
• Run a deeper product challenge session only when the user asks for one. Keep routine work proportional to its risk.

Test: A reviewer can distinguish evidence from agreement and see how each material unknown will be resolved. Questions change a decision or identify a validation step.

3. Ship the Minimum Viable Change

Smallest change that delivers real signal. No speculative scope.

Scope rules:

• Cut to the smallest version that tests the hypothesis - not the full vision.
• No features beyond what was asked. No "while we're here."
• No abstractions for single-use code.
• Avoid speculative configurability and abstractions. Handle the failures necessary for the requested behavior to work safely and reliably.

Edit rules:

• Touch only what the request requires.
• Match existing style; don't refactor what isn't broken.
• Remove orphans your change created; leave pre-existing dead code alone (mention it, don't delete).

Test: Every changed line and every added feature traces directly to the stated problem.

4. Name the Tradeoffs

Every decision costs something. Make the cost visible.

For non-trivial choices, state:

Rules:

• Don't frame options as "right vs wrong." Frame as "optimize for X vs Y."
• Call out irreversible costs (data migrations, public APIs, UX patterns users learn).
• If there's no tradeoff, say so explicitly - that's a signal the choice is obvious or the thinking is shallow.

Test: A stakeholder who disagrees with the decision can still articulate why we chose it.

5. Define Done by Outcome, Not Output

"Merged" is not "done." Done is "the user can do the thing, and it works."

Acceptance criteria must include:

• Functional : Tests pass; edge cases handled.
• User-facing : A real user flow completes end-to-end.
• Operational : It's observable in production (logs, errors, analytics firing).

Transform weak tasks into verifiable goals:

Rules:

• For multi-step work, write the plan as numbered steps with a verify step after each.
• If acceptance criteria can't be written, the work isn't ready to start.

Test: Someone else can check whether the work is done without asking us.

6. Instrument Before You Ship

If we can't measure it, we can't tell if it worked.

For every user-facing or behavior-changing release, define upfront:

• Primary metric : The one number we expect to move
• Baseline : Current value from accessible data. If unavailable, request the evidence or define how to establish it. Never invent a baseline.
• Expected direction & size : e.g. +5% conversion, –20% latency
• Time horizon : When we check (7 days? 30?)
• Guardrail metrics : What must not get worse (error rate, adjacent funnels, cost-to-serve)
• How we'll read it : A/B test, before/after, cohort, qualitative

Rules:

• Ship instrumentation in the same change as the feature. Never "we'll add analytics later."
• If a metric can't be defined, write down what qualitative signal would tell us it's working.
• If nothing will move, reconsider whether to build it.

Test: On day N post-launch, we can answer "did this work?" with data, not opinion.

7. Log the Decision, Flag Reversibility

Decisions compound. Capture them so future-us and new teammates aren't guessing.

For any non-trivial decision, append an ADR-lite entry to .product-mode/decisions/:

## Decision: [short title]
Date: YYYY-MM-DD
Context: [problem, constraints]
Options considered: [A, B, C]
Choice: [X], because [reason]
Reversibility: [one-way / two-way door]
Revisit trigger: [metric / date / condition that reopens this]

Rules:

• Two-way door (easily reversible): decide fast, move on.
• One-way door (costly to undo - public APIs, data schemas, pricing, brand, core UX): require written tradeoffs (Principle 4) and explicit sign-off before proceeding.
• Record decisions that commit meaningful resources, resolve a real tradeoff, or would surprise a future reader. Reuse an existing entry for the same decision; routine implementation choices can stay in the task's checklist.
• Always state a revisit trigger. Without one, decisions calcify into unquestioned defaults.

Test: A new teammate reading the log understands why we're here, not just where we are.