Unknowns discovery

Unknowns Discovery

A structured process for finding what you don't know you don't know — before it finds you during implementation.

Why this exists

The #1 cause of rework isn't bad code — it's building the wrong thing, or building the right thing on wrong assumptions. Most project failures trace back to an assumption nobody questioned, an edge case nobody imagined, or a dependency nobody checked. This skill systematically hunts those down.

The framework has three phases with eight steps total. Not every task needs all eight — a two-line bug fix doesn't need a pitch doc. Scale to the work:

Work size	Steps to run
Bug fix / tiny change	Blindspot Pass (abbreviated) → implement → done
Feature / moderate task	Blindspot Pass → Approaches → Interview → Reference Check → Plan → Implementation Notes
New project / major build	All eight steps

Use judgment. When in doubt, run the Blindspot Pass — it takes 5 minutes and catches things the other steps won't.

How to use this skill

When this skill triggers, follow the phases below in order. Each phase produces a concrete artifact saved to unknowns/ inside the project directory (create it if it doesn't exist). The artifacts compound — later phases reference earlier ones.

Before starting: read the project's CLAUDE.md and CONTEXT.md if they exist. These are the project's own memory and will ground everything that follows.

---

PHASE A: PRE-IMPLEMENTATION

These steps happen before writing any implementation code. The goal is to shrink the space of unknown-unknowns so that when you start building, you're building the right thing in the right way.

Step 1 — Blindspot Pass

Goal: Scan the entire project for things that could bite you later.

Why this matters: Developers (human and AI) naturally focus on the happy path. The blindspot pass deliberately looks everywhere else — the error paths, the implicit assumptions, the things that "obviously" work until they don't.

Process:

1. Read the codebase broadly. Don't just read the files relevant to the current task — skim adjacent systems, shared utilities, config files, and tests. You're looking for context, not just code.

2. Read all project docs: CLAUDE.md, CONTEXT.md, README.md, any specs or design docs in the project folder.

3. Identify and categorize unknowns into these buckets:

   • Unvalidated assumptions — things the code or docs assume to be true but never verify. "This API always returns in < 200ms." "Users will have iOS 17+." "The database row will exist by the time this runs."

   • Missing error handling — what happens when the network is down, the API returns 500, the user's input is garbage, the disk is full, the background task gets killed mid-operation?

   • Dependency risks — external services, third-party libraries, or system capabilities that could change, break, or behave differently than expected. Pay special attention to version-pinning, deprecation warnings, and APIs in beta.

   • Architectural fragility — design decisions that work now but would break under load, at scale, or if requirements shift. Tight coupling between components. Single points of failure. Hardcoded values that should be configurable.

   • Spec gaps — places where the requirements are vague, contradictory, or silent. "The user should be able to manage their data" — what does "manage" mean? What data? All of it?

   • Data integrity risks — race conditions, stale caches, missing migrations, implicit ordering assumptions, writes without rollback paths.

4. For each unknown, note severity (how bad if it bites) and likelihood (how likely it is to actually happen).

Output: Write unknowns/blindspot-report.md with sections: Critical (high severity + moderate+ likelihood — include impact, evidence with file:line, and suggested mitigation for each), Watch (moderate severity or low likelihood), Low-risk notes, and Validated assumptions (things that checked out — cite the code/doc that confirms them). The validated-assumptions section matters: it prevents re-investigating the same things next time.

---

Step 2 — Brainstorm Multiple Approaches

Goal: Generate 3+ different ways to accomplish the task, with honest tradeoffs for each.

Why this matters: The first approach that comes to mind is usually the most obvious one, not the best one. By forcing yourself to generate alternatives, you discover tradeoffs you wouldn't have considered, and sometimes find an approach that's simpler, more robust, or better aligned with the existing codebase. Even if you end up picking the obvious approach, you'll pick it knowingly rather than by default.

Process:

1. Generate at least 3 approaches. Include:

   • The obvious/conventional approach
   • A simpler/faster approach (what's the minimum viable version?)
   • An unconventional approach (what if you solved the problem differently than expected? Used a different data structure? Skipped a step? Inverted the control flow?)

2. For each approach, evaluate:

   • Implementation effort — hours/days, not "easy/medium/hard"
   • Maintainability — how easy is this to understand, modify, and debug in 6 months?
   • Risk profile — which unknowns from the blindspot pass does this approach mitigate vs. amplify?
   • Compatibility — how well does this fit with existing patterns in the codebase?
   • What could go wrong — the specific failure mode for this approach

3. Make a recommendation, but hold it loosely. The user knows their context better than you do.

Output: Write unknowns/approaches.md. For each approach: 2-3 sentence summary, effort estimate, maintainability assessment, risk profile (which blindspots it hits/avoids), compatibility with existing patterns, and specific failure mode. End with a recommendation and explicit callout of what you're less sure about.

---

Step 3 — Interview the User

Goal: Ask pointed, specific questions about the ambiguities you found — not generic "what do you want?" questions.

Why this matters: Vague questions get vague answers. Specific questions surface the decisions that actually affect implementation. "What do you want the error handling to look like?" is useless. "When the Twitter API rate-limits us mid-batch, should we queue the remaining posts and retry in 15 minutes, or abort and notify the user?" — that's a question whose answer changes the code.

Process:

1. Review your blindspot report and approaches doc. Identify the 3-7 questions whose answers would most change how you implement.

2. Prioritize by rework cost — ask first about the things that are hardest to change later. Database schema questions before UI questions. Data model questions before display logic.

3. Frame each question with context so the user understands why you're asking. Don't just ask "should X be Y?" — say "I noticed the current code does X (in file.swift:42), but if we're adding feature Z, that assumption breaks because [reason]. Should we [option A] or [option B]?"

4. Where possible, offer concrete options rather than open-ended questions. The user can always say "none of the above."

5. Include "what I'll assume if you don't have a preference" for each question. This keeps things moving — the user can just confirm defaults rather than making every decision from scratch.

Output: Present questions directly to the user (not a file). After the conversation, record answers in unknowns/decisions.md — one section per question with the decision, rationale (including constraints/preferences mentioned), and impact (which files/systems it affects). This file becomes the "why did we do it this way?" reference for the future.

---

Step 4 — Reference-Based Grounding

Goal: Anchor every implementation decision to existing patterns in the codebase rather than inventing new ones.

Why this matters: Every new pattern is a new thing to learn, maintain, and keep consistent. When a codebase already handles auth a certain way, or structures its models a certain way, or does error handling a certain way, following that pattern eliminates an entire category of unknowns. It also reduces code review friction — the reviewer already knows the pattern.

Process:

1. For each major implementation decision, find the existing precedent in the codebase. Search for:

   • How similar features are structured (file layout, naming, separation)
   • How the project handles the same concerns (auth, validation, error handling, state management, persistence, API calls, navigation)
   • Shared utilities, base classes, or helpers that should be reused
   • Test patterns — how existing tests are structured and what they cover

2. For each pattern you find, explicitly note it: "Auth follows the pattern in AuthManager.swift — token refresh, retry, and logout-on-401 are all handled there. I should use the same authenticatedRequest() wrapper."

3. Flag cases where no existing pattern exists — these are higher-risk areas where you're establishing a new precedent. Call them out so the user can weigh in on the pattern before you set it.

4. Flag cases where existing patterns conflict — e.g., two parts of the codebase handle the same concern differently. These need a decision about which pattern to follow (or whether to unify them).

Output: Fold findings into the implementation plan (Step 5). If the reference audit is substantial, write unknowns/reference-patterns.md.

---

Step 5 — Implementation Plan

Goal: Write a plan that explicitly separates "what I'm confident about" from "what might change."

Why this matters: A rigid spec pretends you know everything upfront. You don't. A good implementation plan is a flexible outline that acknowledges uncertainty — it tells you where to be careful, where to expect pivots, and where to invest in making things easy to change.

Process:

1. Organize the plan by work stream (not by file). Group related changes that should be implemented and tested together.

2. For each work stream, include:

   • What to build (concrete, not hand-wavy)
   • Which existing patterns to follow (from Step 4)
   • Which blindspots from Step 1 are relevant here
   • Which decisions from Step 3 apply
   • Confidence level: "solid" (unlikely to change) vs. "provisional" (might change once you see it working, and here's why)

3. Call out the integration points — where work streams touch each other or external systems. These are where most bugs hide.

4. Include a rough ordering that front-loads the riskiest/most uncertain work. You want to discover problems early, not on the last day.

Output: Write unknowns/implementation-plan.md. Start with the chosen approach (and modifications from interview). Organize by work stream — each stream gets concrete tasks, the pattern it follows, relevant blindspots, and a confidence tag: solid (unlikely to change) or provisional (might change — explain why and include a fallback). End with integration points (where streams touch each other or external systems, and what could go wrong) and open questions that can only be answered by trying.

---

PHASE B: DURING IMPLEMENTATION

Step 6 — Implementation Notes

Goal: Keep a running log of everything that deviates from the plan, every surprise, every on-the-fly decision.

Why this matters: This is where unknown-unknowns become known-knowns. The blindspot pass catches things you can reason about in advance. Implementation notes catch things you can only discover by doing the work — the API that behaves differently than documented, the edge case that only appears with real data, the "simple" task that turned out to be complex.

Process:

Create unknowns/implementation-notes.md at the start of implementation and update it as you work. Log:

• Plan deviations — what you did differently and why. Not a guilt ledger; deviations are expected and healthy. The log exists so you can trace decisions later.
• Discovered edge cases — things that weren't in the blindspot report because they only became visible during implementation.
• Wrong assumptions — assumptions from the blindspot report or plan that turned out to be incorrect. Note what you assumed, what was actually true, and what you changed.
• On-the-fly decisions — choices you made without consulting the user because they were small enough to decide locally. Log them so the user can review and course-correct if needed.
• Technical debt accepted — shortcuts you took deliberately, with a note about why and what "doing it right" would look like.

Output: unknowns/implementation-notes.md — an append-only log. Each entry gets a timestamp, a type tag (deviation / edge-case / wrong-assumption / decision / debt), what happened, why, and its impact on the plan or system. Don't edit previous entries — they're a log, not a living document.

---

PHASE C: POST-IMPLEMENTATION

These steps happen after the code works but before considering the work done. They catch things that slipped through all the previous steps.

Step 7 — Verification Quiz

Goal: Pressure-test your own understanding of what was built and what could break.

Why this matters: It's easy to build something that works for the test cases you thought of without fully understanding why it works — or what conditions would make it stop working. The quiz forces articulation. If you can't answer a question about the system you just built, that's a gap.

Process:

Generate and answer these questions (adapt to the specific project):

1. What files were modified or created? List them and explain what each change does in one sentence.
2. What's the data flow? Trace a request/action from user input to persistence and back. Where does data transform? Where could it be lost?
3. What are the failure modes? If [external service] goes down, what happens? If [input] is malformed, what happens? If [concurrent operation] occurs, what happens?
4. What assumptions does this code make? List them. Are they documented? Are they enforced (assertions, validation) or just hoped for?
5. What was the hardest decision? Why was it hard? What would change your mind about it?
6. What would break if requirements shift? If the user wanted [plausible extension], how much would need to change?
7. What did you learn that isn't in the code? Tacit knowledge — things you now know about the system that someone reading the code wouldn't immediately grasp.

Output: Write unknowns/verification-quiz.md with questions and answers. Flag any question you can't answer confidently — those are residual unknowns that may need attention.

---

Step 8 — Pitch Doc

Goal: Write a short document explaining what was built and why, for someone who wasn't involved.

Why this matters: Explaining your work to a hypothetical outsider forces you to confront hand-wavy reasoning. "We did it this way because it felt right" doesn't survive a pitch doc — you have to say why. This also serves as onboarding material for the next person (or future-you) who touches this code.

Output: Write unknowns/pitch.md with five sections: What we built (2-3 sentences — what it does, who it's for), Why we built it this way (key decisions + rationale, reference decisions.md), What changed from the plan (major deviations — if nothing changed, say so, that's noteworthy), Known limitations (intentional vs. future TODO), and What to watch (residual unknowns, accepted debt, dependencies that might shift).

---

Adapting the process

Not every project needs every step. Here's how to scale:

• Already deep in a project? Skip Step 4 (Reference-Based Grounding) — you already know the patterns. The Blindspot Pass is still valuable because familiarity breeds assumption.

• Picking up someone else's work? Lean heavily on Steps 1 and 4. The codebase is full of implicit decisions you haven't internalized yet.

• Time-pressured? Run Steps 1, 3, and 5 at minimum. The blindspot pass catches the big risks, the interview prevents building the wrong thing, and the plan gives you a map. Add Step 6 (implementation notes) as you go — it's nearly free.

• Reviewing, not building? Run Steps 1 and 7. The blindspot pass and quiz work great as a code review framework.

• Resuming paused work? Run Step 1 on the current state (things may have changed since you last looked), then pick up the existing implementation plan. Check the implementation notes for where you left off.

Working with existing project docs

If your projects keep a CLAUDE.md / CONTEXT.md (or similar agent-facing docs), this skill integrates with them:

• Read them first — they contain project-specific context, conventions, and constraints that directly feed the blindspot pass.
• Don't duplicate them — if something is already documented in CONTEXT.md, reference it rather than restating it.
• Feed back into them — if the unknowns process reveals important project context that should persist beyond this task (e.g., a critical architectural decision, a discovered constraint), suggest adding it to the project's CLAUDE.md or CONTEXT.md so future sessions benefit.

File organization

All artifacts go in unknowns/ inside the project directory:

project-folder/
├── CLAUDE.md
├── CONTEXT.md
├── unknowns/
│   ├── blindspot-report.md
│   ├── approaches.md
│   ├── decisions.md
│   ├── reference-patterns.md  (if substantial)
│   ├── implementation-plan.md
│   ├── implementation-notes.md
│   ├── verification-quiz.md
│   └── pitch.md
└── [rest of the project]

For projects with multiple features in flight, add a subdirectory per feature: unknowns/feature-name/.

Old unknowns artifacts are valuable history — don't delete them when starting a new feature. They document the project's decision trail.