Product Advisor

Product Advisor

Turn a client diagram + conversation into a Business Requirements Document and a resolved gap-list, then seed the harness pipeline. The pre-inception front door: gather requirements with AI, feed them in, and let the existing flow continue as it does today.

When to Use

• At the inception of a client engagement, when a solution architect / pre-sales engineer has a rough idea, a diagram, and conversation notes but no structured requirements yet.
• When you want to turn "a diagram and some notes" into a client-legible BRD plus an explicit list of what is still unknown.
• When the output should seed the roadmap (many work items) and ground the engagement's strategy — not produce a single spec.
• NOT for authoring a spec/proposal — that is harness-brainstorming's job. Product Advisor stops at BRD + roadmap seeding.
• NOT for writing or updating STRATEGY.md directly — that is harness-strategy's job. This skill only reads strategy and offers to seed it.
• NOT for internal feature work where the requirements already live in the codebase or an existing spec — go straight to harness-brainstorming or harness-planning.

Process

Iron Law

Every gap is either resolved in the interview or shipped as an explicit client-facing question — never silently dropped. A BRD that hides what it does not know is worse than no BRD: it launders assumptions into requirements. If you cannot answer a gap and did not surface it in gaps.md, STOP and add it.

---

Phase 1: INGEST — Gather the Raw Material

1. Resolve the engagement slug. From the engagement argument, or ask the SA for a short name. This sets docs/inception/<engagement>/ and the roadmap milestone Inception: <engagement>.
2. Ingest the diagram. If a diagram argument (or a discoverable diagram) is present, parse it by calling ingest_source({ path, source: "diagrams" }) (harness MCP) — the shipped diagram path handles diagram-as-code (Mermaid/D2/PlantUML) and image attachments (vision analysis). Then read the extracted entities and flows back via gather_context / query_graph. Do not build a new parser — reuse ingest_source.
3. Soft-degrade when parsing is unavailable. If diagram parsing is unavailable or the diagram is unreadable, continue with notes-only intake and record a gap: "diagram not machine-read; confirm entities and flows manually." Do not fail.
4. Ingest the notes. Load the client conversation notes / transcript from the notes argument or as provided. Call gather_context to pull any existing project/business knowledge that grounds the domain.
5. Normalize into intake. Produce a structured intake: { entities[], flows[], notes }. State the entities and flows back to the SA in one short summary and confirm before drafting.

---

Phase 2: DRAFT-BRD — Synthesize the First Draft

1. Write the BRD to docs/inception/<engagement>/brd.md with these sections, each present even if thin: Context, Business Objectives, Scope, Functional Requirements, Non-Functional Requirements, Assumptions, Constraints, Out-of-Scope, Open Questions.
2. Phrase behavioral requirements with EARS patterns:
   • Event-driven: "When [trigger], the system shall [response]."
   • Unwanted: "If [condition], then the system shall not [behavior]."
3. Tag gaps against the fixed BRD completeness rubric (see below). Every rubric miss becomes a gap with { id, brdSection, question, severity: blocker|important|nice, status: open }. Do not invent facts to fill a section — an empty-because-unknown section is a gap, not a place to guess.
4. Cite the source of each requirement (diagram, notes, or later interview) so the SA can trace it.

BRD completeness rubric

• Each BRD section is non-empty and internally consistent.
• Every diagram entity and flow maps to ≥1 functional requirement (or to an explicit gap).
• Every functional requirement has an actor + trigger + response.
• Every non-functional requirement is measurable (a number or a testable condition), else it is a gap.
• Scope and Out-of-Scope do not contradict each other.

---

Phase 3: GAP-INTERVIEW — Resolve What You Can

1. Ask ONE question at a time, in plain text. Order the gap queue by severity (blocker → important → nice). Ask the highest-severity open gap first, wait for the answer, then continue.

   Ask directly in your reply. Do NOT route questions through emit_interaction, AskUserQuestion, or any tool — those do not reliably surface the question to the human. Plain text in your own message is the only channel that reaches the SA across every client (Claude Code, Cursor, Codex, Gemini CLI).

   Present each gap as a scannable multiple-choice table where options exist, and state a recommendation:

   ### Gap G3 (blocker): What authenticates end users?
   
   |             | A) Client SSO (SAML/OIDC) | B) Local accounts | C) Unknown — ask client |
   | ----------- | ------------------------- | ----------------- | ----------------------- |
   | **Implies** | IdP integration work      | Password storage  | Blocks scoping          |
   | **Risk**    | Depends on client IdP     | Security burden   | —                       |
   
   **Recommendation:** likely A given the enterprise diagram — confirm the IdP.
   

2. Fold each answer back into the BRD. Update the relevant section, add the requirement (source: interview), and move the gap open → resolved with the captured answer.

3. Mark unresolvable gaps client-facing. If the SA cannot answer (only the client can), keep the gap open and phrase it as a question to ask the client.

4. Stop when the queue is drained — every gap is either resolved or open (client-facing). Do not loop past a drained queue inventing new questions.

---

Phase 4: FINALIZE — Ship and Hand Off

1. Write gaps.md to docs/inception/<engagement>/gaps.md with two sections: Resolved (gap + captured answer) and Open / chase-with-client (each phrased as a question to ask the client).
2. Offer a STRATEGY.md seed. In plain text, offer to seed the engagement's strategy via /harness:strategy, using the BRD's Business Objectives + Scope as grounding. Never write STRATEGY.md yourself — dispatch harness-strategy if the SA accepts.
3. Fan out into roadmap candidates. Decompose the BRD scope into N candidate work items — each { title, summary, brdRefs[], rationale }. Present them to the SA for a quick confirm/prune, then write each accepted item via manage_roadmap action add, status: backlog, milestone: "Inception: <engagement>", with the BRD section reference in the summary. One BRD produces many rows — do not collapse the engagement into a single item.
4. Emit the handoff. Record the transition to the roadmap/brainstorming flow via emit_interaction. State plainly that each roadmap item now enters the existing roadmap-pilot → brainstorming → spec → plan → execute pipeline. Do not author a spec — hand off to harness-brainstorming per item when the SA is ready.

---

Harness Integration

• gather_context — Phase 1: pull existing project/business knowledge to ground the domain.
• ingest_source (source: "diagrams") — Phase 1: parse diagrams (diagram-as-code + image vision) into the knowledge graph; read the extracted entities/flows back via gather_context / query_graph. Never reimplement the parser.
• read_strategy — Phase 4: read STRATEGY.md (if present) to align the BRD; never write it.
• manage_roadmap (action add) — Phase 4: create backlog roadmap rows from the BRD fan-out.
• emit_interaction — Phase 4: record the handoff transition to the roadmap/brainstorming flow.
• harness validate — After finalize: verify artifact placement and project health.

Success Criteria

• Running the skill with a diagram + notes produces docs/inception/<engagement>/brd.md with all required sections, none empty.
• Every diagram entity/flow maps to ≥1 BRD requirement or to an explicit gap.
• gaps.md exists and separates Resolved from Open/client-facing; every open gap is phrased as a question.
• The gap interview asked one question at a time and folded each answer into the BRD (resolved gaps moved open → resolved).
• finalize created ≥1 candidate roadmap row via manage_roadmap, each linking back to a BRD section.
• finalize offered a STRATEGY.md seed via /harness:strategy and did not write STRATEGY.md directly.
• Behavioral functional requirements use EARS phrasing.
• When diagram parsing was unavailable, the skill degraded to notes-only and recorded a gap rather than failing.
• No spec/proposal was authored by this skill.

Examples

Example: retail loyalty engagement from a diagram + call notes

INGEST:

engagement: acme-loyalty
diagram: architecture.mmd (Mermaid) → parsed: entities [POS, Loyalty API, CRM, Rewards Engine], flows [POS→Loyalty API→CRM]
notes: kickoff-call.md → loaded. gather_context: existing "loyalty" business facts surfaced.
Confirmed entities/flows with SA. Proceed.

DRAFT-BRD: Wrote docs/inception/acme-loyalty/brd.md. 9 sections. Tagged 6 gaps: G1 (blocker) no auth model; G2 (blocker) Rewards Engine has no defined trigger; G3 (important) no NFR for POS latency; G4 (important) CRM data residency unknown; G5 (nice) reporting cadence; G6 (blocker) "Rewards Engine" entity maps to no requirement.

GAP-INTERVIEW:

G1: "What authenticates end users? A) Client SSO B) Local C) Unknown" → SA: "A, Okta OIDC." → folded in.
G2: "When does the Rewards Engine fire? A) On transaction B) Batch nightly C) Unknown" → SA: "A." → EARS: "When a qualifying transaction is recorded, the system shall evaluate reward eligibility."
G3: "POS latency budget?" → SA: "client must confirm." → kept open, client-facing.
G4: "CRM data residency?" → SA: "client must confirm." → kept open, client-facing.
G6: resolved by G2. G5: SA: "monthly." → folded in.

FINALIZE:

Wrote gaps.md → Resolved: G1,G2,G5,G6 | Open/client-facing: G3 (latency), G4 (residency).
Offered STRATEGY.md seed → SA accepted → dispatched /harness:strategy.
Roadmap fan-out (milestone "Inception: acme-loyalty", backlog):
  - "POS ↔ Loyalty API integration" (brd: Scope, FR-1)
  - "Rewards Engine eligibility rules" (brd: FR-4)
  - "Okta OIDC authentication" (brd: FR-2)
  - "CRM sync + residency compliance" (brd: FR-5, NFR-2)
Emitted handoff → each item enters roadmap-pilot → brainstorming. No spec authored.

Gates

• No dropped gaps. Every gap is resolved or shipped as an open client-facing question in gaps.md. A gap that is neither = Iron Law violation; stop and fix.
• No guessed requirements. A BRD section that is unknown is a gap, not a place to invent facts. Fabricating a requirement to fill a section is a hard stop.
• No writing STRATEGY.md. This skill reads strategy and offers to seed it via /harness:strategy. Writing STRATEGY.md directly = gate violation.
• No authoring specs. This skill stops at BRD + roadmap seeding. Writing a proposal.md = gate violation; hand off to harness-brainstorming.
• No single-item collapse. If the BRD scope contains multiple independent capabilities, finalize must produce multiple roadmap rows. Collapsing an engagement into one row defeats the fan-out.
• No hard failure on missing diagram. Absent/unreadable diagram → notes-only + recorded gap. Aborting the run because a diagram would not parse = gate violation.

Escalation

• Diagram parses but entities contradict the notes: Do not silently pick one. Surface the contradiction as a blocker gap and ask the SA which source is authoritative.
• The SA cannot answer any blocker gap: The engagement is too early for a BRD. Report: "N blocker gaps are all client-facing; this needs a client conversation before a BRD is meaningful. Ship the gap-list as a client questionnaire and pause."
• Scope keeps expanding during the interview: Stop. Report: "Scope has grown beyond the ingested material. Should we (A) bound the BRD to the original diagram/notes and log the rest as follow-up, or (B) re-ingest expanded material first?"
• manage_roadmap is unavailable: Write the candidate items into gaps.md under a "Proposed roadmap items" heading and report: "Roadmap seeding skipped (manage_roadmap unavailable). Re-run finalize when MCP is restored."
• More than ~15 gaps after drafting: The intake is too raw. Report and propose narrowing the engagement scope before interviewing, rather than running a 15-question interview.

Rationalizations to Reject

Rationalization	Reality
"The diagram implies the auth model, so I'll just write it as a requirement"	An implication is not a confirmation. Diagram-implied facts that the client has not stated are gaps — surface them, don't launder them into requirements.
"This gap is minor, I'll leave it out of gaps.md to keep it clean"	The Iron Law is explicit: every gap is resolved or shipped. A gap you drop is an assumption the client discovers in production. nice-severity still ships.
"I have enough to draft a proposal, I'll just write the spec too"	Product Advisor stops at BRD + roadmap seeding. Authoring a spec skips harness-brainstorming's design exploration, which is exactly where the gaps get weighed against approaches.
"The BRD's objectives are clear, I'll seed STRATEGY.md directly to save a step"	This skill never writes STRATEGY.md. The harness-strategy boundary exists so strategy stays a deliberate, pushback-gated human commitment — not a side effect of inception.
"The engagement is really one big project, I'll make one roadmap row"	A BRD describes a solution scope that fans out into many work items. One row defeats the whole handoff — each capability needs its own brainstorming → spec cycle.
"The diagram won't parse, so I can't run — I'll abort"	Notes-only intake is a first-class path. Degrade, record the diagram as a gap, and continue. Aborting throws away the requirements the notes already contain.

Red Flags

Flag	Corrective Action
"I'll fill the empty NFR section with reasonable defaults"	STOP. Unknown NFRs are gaps. Defaults you invent become requirements no one agreed to. Tag it as a gap and ask.
"The interview is dragging; I'll batch the remaining questions into one message"	STOP. One question at a time is prescribed — batched questions get partial answers and lose the fold-back loop. Ask the next single highest-severity gap.
"The SA said 'just make sensible assumptions'"	STOP. Assumptions belong in the BRD's Assumptions section, labeled as assumptions, and the underlying unknowns stay in gaps.md as client-facing. Do not convert assumptions into silent requirements.
// TODO: confirm with client left inside brd.md functional requirements	STOP. Confirmation-needed items are gaps, not requirements. Move them to gaps.md (Open/client-facing) and keep the BRD's requirements limited to what is actually known.

---