Clarify the problem before you code

What this lesson gives you

A stakeholder says, “Add a filter to the task list.” Coding immediately would force someone—often the AI—to invent missing meaning: which user is struggling, what is wrong now, and what should be observably different when the problem is solved.

This lesson produces Problem Brief v1, a deliberately small pre-code artifact. It closes only three ideas: an engineering-ready problem, an observable outcome, and a clear separation of facts, assumptions, and unknowns. It does not select the implementation, finish scope and constraints, or write acceptance criteria. FND-001-P02 owns only the next scope/constraints/non-goals work after the problem is known; acceptance criteria remain deferred downstream and are not assigned to P02 by this Bible.

Estimated active time: 45 minutes.

Use this lesson when: a change request is short, solution-shaped, or likely to make humans and AI fill gaps differently.

Do not use it as: an implementation plan, architecture decision, full scope box, or acceptance-criteria specification.

Hard prerequisite — ORI-006: you must be able to distinguish supported facts from unsupported claims and identify the evidence/authority behind an important statement.

Short ORI-006 prerequisite probe

Before choosing a route in this lesson, inspect this small evidence packet:

• Claim: “Raven CLI 4 is approved for production use by this team.”
• Evidence A: an official vendor support page says Raven CLI 4.x has product support through the end of 2027.
• Evidence B: a team wiki dated January 2025 says “only Raven 3 is approved,” but its owner and review status are unknown.
• Evidence C: an undated screenshot shows Raven CLI 4 launching successfully on one machine.

In four lines, state the exact claim boundary, what each source is actually authoritative for, what remains unknown, and your ACCEPT / MODIFY / DEFER decision.

Deterministic PASS is 4/4: (1) do not equate vendor product support with internal team approval; (2) do not treat a successful-run screenshot as production-approval evidence; (3) keep internal approval unknown until authority/freshness is resolved; (4) do not ACCEPT the current claim without more evidence—choose MODIFY or DEFER and justify it.

If any one of the four criteria fails, do not continue. Use a targeted ORI-006 bridge only for that failure: for authority errors revisit “Match source class to claim type,” for provenance/freshness revisit “Seven checks before ACCEPT,” and for decision closure revisit “ACCEPT, MODIFY, or DEFER” plus “Final card check.” Then retry this probe once; enter FND-001-P01 only after 4/4.

Choose your support route

All routes end at the same artifact and evidence bar; only the scaffolding changes.

Three-concept route probe

Before choosing a route, answer these three items without reading the explanations below:

1. K01: rewrite “build a blue Filter button” so it states only the current gap and requires no solution.
2. K02: turn “the work is done when the PR is merged” into an external observable outcome.
3. K03: “the filter must persist across sessions” has no evidence; classify it as fact / assumption / unknown and justify the status in one line.

An item passes only if it demonstrates that concept independently without importing a downstream decision. 3/3 → Experienced/Fast Path; 2/3 → Repair only the failed concept; 0–1/3 → Foundation. Repair map: K01 and K02 return to “The three foundation concepts”; K03 returns to “Fact, assumption, and unknown” and, if needed, “Three plausible failure modes.”

• Foundation: work through the shared task-filter case with the visible artifact structure.
• Repair: revisit only the concept that failed in the route probe; do not replay concepts already demonstrated.
• Experienced / Fast Path: only after a full 3/3 PASS, jump directly to the stable independent-practice target. Your case contains incomplete or conflicting information.

Fast Path does not lower the standard. You still have to produce a reviewable Problem Brief v1 and defend its boundaries.

A three-question pause before “how”

Ambiguous requests tend to skip straight to implementation. Before asking how to build anything, close three questions:

1. What gap exists now? Describe the current shortfall for a specific actor/context without embedding a solution.
2. What would be observably different if the problem were solved? The outcome must be visible or measurable without reading the code.
3. What do we know, what are we assuming, and what is still unknown? Every decision-relevant statement needs an explicit status.

Asset TA-001 externalizes this as concept → artifact field → evidence → boundary. It uses no invented score or metric.

Boundary rule: scope, constraints, non-goals, and acceptance criteria are not completed here. Keep scope/constraints/non-goals questions for FND-001-P02. If the open question concerns acceptance criteria, record it only as a later downstream decision; this Bible does not assign that ownership to P02.

The three foundation concepts

1. Engineering-ready problem

A useful problem statement describes the gap between the current state and the needed result. It is not a task list or a preferred implementation.

Weak: “Build a Filter button.” Better: “In a mixed list of completed and unfinished tasks, the user cannot quickly restrict the view to unfinished work.”

Quick check: can another person identify what is currently missing or wrong without guessing the solution?

2. Observable outcome

An outcome is an external behavior or result. “The code is merged” and “the component exists” describe work performed, not the user-visible result.

For the shared case: “The user can view only unfinished tasks and then return to the full list.” This still leaves implementation choices open.

3. Fact, assumption, and unknown

• A fact has evidence or an identifiable authority.
• An assumption is plausible but not yet confirmed.
• An unknown still needs an answer or must remain explicitly unresolved.

“Persist the filter across browser sessions” is not a fact merely because it sounds reasonable. Without supporting authority, keep it as an assumption or unknown.

Build Problem Brief v1 without turning it into a mega-spec

The artifact should be small enough to create before coding and strong enough to stop two people from solving different problems.

A strong Problem Brief does not solve the whole project. It makes the starting point honest.

Where AI helps—and where it stops

AI can critique vague wording, suggest alternate interpretations, surface possible unknowns, or check the artifact for internal consistency. It cannot legitimately invent stakeholder intent, silently promote an unknown into a requirement, or act as the acceptance authority. Human judgment and traceable evidence own those decisions.

Worked case: “add a filter”

Initial request: “Add an unfinished filter to the task list.”

Plausible but wrong brief: “Add a blue toggle, store state in the URL, and call it done when the component ships.” That sentence smuggles in a UI solution, a persistence decision, and an activity-based definition of success.

Bounded Problem Brief v1:

• Actor/context: a user working in a mixed list of completed and unfinished tasks.
• Current gap: the current experience does not provide a clear way to restrict the view to unfinished tasks.
• Observable outcome: the user can view unfinished tasks only and return to the full list.
• Fact: task data includes completed/unfinished state in the supplied case.
• Assumption: users may want the filter selection to persist across sessions; no evidence supports that yet.
• Unknown: whether persistence or a shareable URL is needed.
• Handoff to P02: persistence, UI constraints, and exact behavioral scope remain unresolved.

Nothing here requires a button, checkbox, query string, or framework. The problem can survive a later implementation change.

Three plausible failure modes

Failure 1: solution disguised as problem

“Build a filter button” may be a candidate solution, but it does not identify the gap. Repair it by removing the implementation and stating what is currently inadequate.

Failure 2: activity disguised as outcome

“Done when the PR is merged” describes team activity. Repair it by describing what a user or external observer can see after the problem is solved.

Failure 3: assumption disguised as constraint

“Store it in the URL” needs authority. Without it, classify the statement honestly and carry the unresolved decision forward.

The common principle is simple: speed does not justify hiding uncertainty. An explicit unknown is safer than a fictional requirement.

Experienced bridge: conflicting evidence

Real work often contains contradictions, not just missing information:

• the ticket says “unfinished only”;
• an old screenshot shows three filter states;
• a team message mentions persistence but may no longer be authoritative.

Do not resolve the conflict by intuition. Keep supported statements as facts, downgrade weak evidence to assumption/unknown, and record which questions must be answered before downstream scope decisions. A brief may remain partially unresolved; false certainty is not progress.

What closes now, and what deliberately stays open

There are two bad extremes: jumping into implementation before understanding the problem, or writing such a large specification that this lesson steals every downstream decision.

Here, only three informational decisions close: the gap, the external outcome, and the status of facts/assumptions/unknowns. That boundary is intentional. It keeps the artifact quick to review while preventing the solution from hardening too early.

If answering “what should change?” forces an exact scope, constraint, or non-goal decision, preserve that question for P02. If it raises an acceptance-condition question, keep that question open for a later downstream stage; do not settle it here and do not assign it to P02 without authority.

Guided and independent practice

Guided case

An internal order tool receives the request, “Add search.” Operators currently page through orders to find a specific one. Order numbers exist in the data. It is unknown whether search should cover customer names, order numbers, or both.

Build Problem Brief v1 without choosing a UI. Include an observable outcome and at least one explicitly classified fact/assumption/unknown.

Independent case — Fast Path destination

In a learning platform, some users upload the same assignment twice because they are unsure whether the first upload succeeded. Support reports confirm duplicate uploads. The system already shows a success message after completion, but its timing and visibility have not been evaluated. Someone proposes, “Add a progress bar.”

Create Problem Brief v1 without copying the task-list wording. End by separating three things: what this lesson must establish, which scope/constraint/non-goal questions remain for FND-001-P02, and any acceptance question that remains open as a later downstream decision and is not assigned to P02.

Verification: what counts as enough evidence?

Check four critical dimensions before moving on:

1. Concept closure: all three concepts are present and correctly distinguished.
2. Independent readability: a reviewer who has not seen the code can identify the current gap and expected external outcome.
3. Neighbor boundary: scope/constraints/non-goals have not been silently completed on behalf of FND-001-P02; acceptance criteria are not completed in P01 and are not assigned to P02 without authority.
4. Human ownership: important statements are traceable or explicitly unknown; AI is not treated as the final authority.

The prerequisite also matters here. If you cannot explain why a “fact” is supported, return to the relevant ORI-006 repair rather than proceeding with a fragile artifact.

The evidence for this lesson is Problem Brief v1 plus a boundary explanation and at least one human-owned decision justified from evidence or explicit uncertainty.

Assessment and transfer

The assessment covers five moves: explain a bounded distinction, build the artifact from a fresh case, diagnose a plausible failure, judge an ambiguous AI proposal, and transfer the artifact to a different domain. Blocking items require inspectable evidence and rationale; a bare answer is insufficient.

In transfer, preserve the three invariants without copying surface wording: a clear gap, an external outcome, and explicit fact/assumption/unknown status. Hand only scope/constraint/non-goal questions to FND-001-P02; if an acceptance question appears, keep it open as downstream work without assigning it to P02.

References and freshness

The lesson’s core concepts come from locked internal curriculum authority. No external standard or vendor workflow defines the MAKNOW artifact format.

For requirements-engineering context, ISO/IEC/IEEE 29148 was rechecked on 2026-09-05. The 2018 Edition 2 remains the published International Standard and is marked “to be revised”; Edition 3 is currently a Draft International Standard under development and has not replaced the 2018 publication.

This lesson makes no current product-specific claim about Codex, Copilot, or Claude workflows. Their live documentation is therefore not used as authority for learner decisions in this version. Any future product-specific claim must be rebound to a current primary source with a new retrieval date.