Imported from I-Synergy/I-Synergy.Framework (.ai/skills/design-interrogation/SKILL.md). Install upstream with npx skills add I-Synergy/I-Synergy.Framework --skill design-interrogation. Copyright stays with the author.

Design Interrogation

Relentless, structured interrogation of a plan or design. Walk every branch of the decision tree, resolve dependencies between decisions one-by-one, and reach a shared understanding before closing.

What This Skill Does

• Interviews the user on every aspect of their plan, one focused question at a time
• Maps the decision tree, tracking which branches are resolved, deferred, or blocked
• Recommends a concrete answer with reasoning for each question asked
• Explores the codebase to answer questions that can be resolved without user input
• Summarizes all decisions and open items when interrogation is complete

Interrogation Protocol

Session Start — Load Required Skills

Before asking the first question, load these three skills. They are active throughout the entire session — not just at the end:

Then create the decision log (see Progressive Document Capture below) and start Phase -1.

Phase -1: Document Intake

Before asking any question, check if the user has existing documents to share.

Before we start: do you have any existing documents I should read first? (business case, PRD, architecture spec, migration plan, functional design) If so, share them — I'll save them to docs/input/ and extract what's already decided.

If documents are provided:

1. Save them to docs/input/ (e.g. docs/input/business-case.md)
2. Read and analyze them — identify any bounded contexts already named in the documents
3. Extract all decisions already made — log them to session-decisions.md as Pre-Resolved
4. Run extractions in parallel using the skills below — do NOT define extraction logic here:
   • If BCs already identifiable → spawn one extractor per BC, each running both skills in parallel
   • If BCs not yet known → run both skills in parallel (single BC assumed, renamed after Phase 0)
   • → usecase-specification/SKILL.md — Mode 0 for use cases
   • → user-story/SKILL.md — Mode 0 for user stories
5. Announce: "Extracted [N] use cases and [M] user stories — [X] gaps marked [OPEN]."
6. Proceed to Phase 0 with only the open questions remaining

If no documents → proceed directly to Phase 0.

Phase 0: Strategic Anchor

Before starting depth-first interrogation, ask these four questions together in a single response. They establish the business context and architectural shape in one round and allow the rest of the session to be focused — or skipped — accordingly.

Present all four at once, clearly numbered A1–A4:

A1 — Business Case

Is this greenfield (new system), migration (replacing an existing system), or an extension of an existing system?

My recommendation: [infer from context the user provided]

A2 — Purpose & Scope

What are we building and what is explicitly out of scope?

My recommendation: [scoped interpretation based on what the user described]

A3 — Architecture Shape

Event-driven with event sourcing, event-driven with state-based persistence, or direct request/response?

My recommendation: [based on domain complexity and existing stack]

A4 — Hard Constraints

What is non-negotiable? (team size, deadline, existing stack, compliance, cloud vs. on-premise)

My recommendation: [infer from codebase — check Directory.Packages.props and Aspire AppHost for existing choices before asking]

After all four are answered, adapt the interrogation order based on A1:

• Greenfield → standard dimension order (1 → 2 → 3 → … → 8)
• Migration → pull Dimension 8 (Migration & Rollout) forward after Dimension 2
• Extension → run codebase-first checks before any question; most decisions are pre-resolved

Then proceed to Phase 1 if 2+ BCs were identified, otherwise depth-first on the highest-impact open dimension.

Phase 1: Parallel BC Interrogation

When Phase 0 (A2) identifies 2 or more bounded contexts, spawn one sub-agent per BC and run them in parallel. Each agent covers Dimensions 2–6 for its BC only.

Trigger:

BCs identified in A2 ≥ 2?
  YES → Spawn N BC agents in parallel (one per BC)
  NO  → Continue single-agent depth-first from Phase 0

Per-BC dimensions:

Each BC agent writes immediately to:

• session-decisions.md — its own BC section
• docs/bounded-contexts/{BC}/use-cases.md — draft use cases as flows resolve
• docs/bounded-contexts/{BC}/user-stories.md — draft stories as criteria are agreed
• Follows the depth-first rule within its own BC

Coordination agent (main session) batches one open question per BC per round:

**BC: OrderManagement — Question 1 — Domain Model**
[question + recommendation]

**BC: Inventory — Question 1 — Domain Model**
[question + recommendation]

After all BC agents complete:

1. Cross-BC integration questions (how do BCs communicate?)
2. Dimension 7 — Non-functionals (global, single agent)
3. Dimension 8 — Migration & Rollout (global, single agent)

Question Format

Ask one question at a time. Each question must be specific, answerable, and accompanied by a concrete recommendation. Use this format:

Question N — [Topic]

[The question, clearly stated.]

My recommendation: [Your concrete recommendation and the reasoning behind it.]

Do not list multiple questions at once. Depth-first: fully resolve one branch before moving to the next sibling.

Decision Dimensions

Cover these areas in dependency order — skip dimensions that are clearly irrelevant or already resolved:

Codebase Exploration

Before asking the user about something that can be determined from the codebase, explore the codebase first. Announce what you found:

I checked the codebase and found that X is already handled by Y — moving on.

Use the Read, Grep, and Glob tools to inspect relevant files. Do not ask the user to confirm what the code already tells you.

Decision Tree Tracking

Maintain a mental model of the decision tree during interrogation:

• Open — decision not yet reached
• Resolved — decision made, no open sub-questions
• Deferred — user consciously chose to decide later
• Blocked — cannot proceed without external information

When a decision opens new sub-questions (e.g., choosing an event-driven approach raises questions about the event schema), explore those sub-questions before moving to the next top-level topic.

Progressive Document Capture

Do not wait until the end of the session to write output. Capture decisions, domain terms, use cases, and user stories as they emerge — this ensures nothing is lost if the session is interrupted, and makes Steps 4–6 a finalization pass rather than a cold generation from memory.

Session Start — Create Decision Log

Before asking the first question, create the decision log file:

docs/session-decisions.md

Use this header:

# Session Decisions — {SolutionName}

> Live decision log. Updated after each resolved question. Finalized into the full architecture document at session end.

## Decisions

| # | Dimension | Decision | Rationale |
|---|-----------|----------|-----------|

After Each Resolved Question

Immediately append to session-decisions.md:

| {N} | {Dimension} | {chosen approach} | {brief rationale} |

Announce:

📝 Logged to session-decisions.md.

When a Domain Term Emerges

As soon as a term is used and agreed upon, append it to UBIQUITOUS_LANGUAGE.md (create the file if it does not yet exist, mark it [DRAFT] in the title until the full ubiquitous-language skill finalizes it):

## [DRAFT] Ubiquitous Language — {SolutionName}

| Term | Definition | Bounded Context | Notes |
|------|-----------|-----------------|-------|
| {Term} | {Definition} | {BC} | [DRAFT] |

When a Use Case Becomes Clear

As soon as the main flow of a bounded context resolves, use usecase-specification skill Mode 1 to write the draft entry to docs/bounded-contexts/{BoundedContext}/use-cases.md.

→ Follow the draft entry format defined in usecase-specification/SKILL.md — Mode 1. Do NOT use a custom format here.

When User Stories Emerge

As soon as acceptance criteria for a feature are agreed, use user-story skill Mode 1 to write the draft entry to docs/bounded-contexts/{BoundedContext}/user-stories.md.

→ Follow the draft entry format defined in user-story/SKILL.md — Mode 1. Do NOT use a custom format here.

Steps 4–6 Become Finalization

When interrogation is complete, Steps 4–6 do not generate from scratch — they complete and finalize the drafts already written:

• Remove all [DRAFT] markers
• Fill gaps in use cases (alternate flows, Gherkin)
• Add Gherkin to user stories, validate INVEST
• Complete the architecture document from session-decisions.md

Architecture Document

Step 1: Load Relevant Instruction Files

Before writing the architecture document, load any instruction files that apply to the technology choices made during interrogation. If your project maintains instruction files in .github/instructions/ or .ai/reference/, load those relevant to:

• Core architecture (Clean Architecture layers, DDD, naming conventions)
• CQRS and error handling
• Data access and ORM patterns
• Authentication and authorization
• Observability and testing patterns

Step 2: Check for Violations

Scan the draft architecture document for these FORBIDDEN patterns:

Step 3: Document Pattern Rationale

For each major pattern, include a brief ADR explaining why this implementation was chosen. Refer to .ai/project/architecture.md for the ADR template.

Step 4: Finalize Session Deliverables (MANDATORY)

The three required skills were loaded at session start and have been capturing drafts throughout the interrogation. This step finalizes those drafts — it is not a cold generation from memory.

Finalization Order

Execute in this sequence — each builds on the previous:

1. Ubiquitous Language first — finalize all draft terms; canonical vocabulary must be locked before use cases and stories are completed.

2. Use Case Specifications second — complete all draft use cases using finalized terminology. Add Gherkin for every main and alternate flow.

3. User Stories third — complete all draft stories using finalized terminology and use cases. Add Gherkin traced to every acceptance criterion. Validate INVEST.

Announce Each Deliverable

Before starting each deliverable:

Deliverable 1 of 3 — Ubiquitous Language Finalizing draft terms from the interrogation…

After completing each:

✅ UBIQUITOUS_LANGUAGE.md finalized — N terms defined, M ambiguities resolved.

Skip Only With Explicit User Consent

If the user says "skip use cases" or "no stories needed", mark the deliverable as Deferred and include it in the closing summary. Never silently skip.

Step 5: Solution Generation Handoff

The session deliverables are direct pipeline inputs for solution generation:

Pipeline execution order:

1. Run solution-generator — pass architecture document as input
2. Translate each user story to a vertical-slices blueprint JSON for feature-by-feature implementation
3. Run gap-review — mandatory after generation, validates against original design decisions

Closing Summary

When all branches are Resolved or Deferred, present a structured summary:

## Interrogation Summary

### Decisions Made
- [Topic]: [chosen approach and brief rationale]

### Deferred Decisions
- [Topic]: Deferred because [reason]

### Remaining Open Questions
- [Any unknowns that require external input]

### Session Deliverables
| Deliverable | Status | File |
|-------------|--------|------|
| Architecture Document | ✅ Complete | `docs/architecture/{SolutionName}-architecture.md` |
| Ubiquitous Language | ✅ Complete / ⏸️ Deferred | `UBIQUITOUS_LANGUAGE.md` |
| Use Case Specifications | ✅ Complete / ⏸️ Deferred | `docs/bounded-contexts/{BC}/use-cases.md` |
| User Stories | ✅ Complete / ⏸️ Deferred | `docs/bounded-contexts/{BC}/user-stories.md` |

### Recommended Next Steps
1. Run [`solution-generator`](../solution-generator/SKILL.md) — pass architecture document as input
2. For each BC: translate user stories to [`vertical-slices`](../vertical-slices/SKILL.md) blueprint JSON
3. Run [`gap-review`](../gap-review/SKILL.md) after generation

Example Exchange

User: grill me on my new notification service

Claude:

Question 1 — Delivery Channels

Which notification channels must the service support at launch — email only, or also SMS, push notifications, or in-app?

My recommendation: Start with email and in-app. SMS adds third-party costs and compliance complexity (GDPR/TCPA). Push requires device registration infrastructure. Both can be added in v2 once the channel abstraction is validated.

After the user answers, follow the dependency tree. If the user says "email and in-app", the next question targets the email provider decision — not an unrelated topic.

Related Skills