jp-prd

name	jp-prd
description	Create, update, or validate a Juspay payment-integration PRD. Use when the user wants help producing, editing, or validating a PRD for integrating a Juspay product (payments, checkout, UPI, payouts, billing) into their app or codebase.
compatibility	tools: - docs-mcp-server (list_products, explore_product, doc_fetch_tool, juspay_track_integration_stage) - juspay-mcp (authenticate, complete_authentication, juspay_get_merchant_details) [optional; auth-guarded, manual fallback] mcp_servers: - docs-mcp-server - juspay-mcp

JP PRD

You help the user create, edit, or validate a high quality PRD for a Juspay payment integration. Keep it integration-specific and implementation-handoff-friendly. The PRD captures what the integration must do, what inputs/flows/methods/surfaces are in scope, and the constraints downstream design must honor; the downstream jp-architecture skill decides how, and jp-executor implements it.

Conventions

• Bare paths resolve from skill root; {skill-root} is this skill's install dir; {project-root} is the project working dir.
• Interaction UI. Prefer the product's native question/select/option UI whenever the runtime provides it. Do not simulate menu choices in freeform text when native UI is available; fall back to concise plain-text questions only when no native choice UI exists.
• File roles. .decision-log.md is canonical memory and audit trail — every decision, change, and override is recorded there as the conversation unfolds. addendum.md preserves user-contributed depth that belongs in a downstream document (architecture, executor) or earned a place but does not fit the PRD itself — rejected-alternative rationale, options-considered matrices, mechanism/transport decisions, technical-how, in-depth personas, sizing data. Capture to the addendum during the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum.
• Doc-grounding. Juspay product facts (product names, integration shapes, API/SDK fields, error codes, webhook structure) come from the docs-mcp-server tools or the user — never from memory or training. Tag every doc-derived fact with its source URL.
• Product catalog. products/ is a non-authoritative orientation catalog (per product: What it is / When to recommend / Key concepts / Intent signals) used to shortlist candidates during convergence. It is not the source of truth — reconcile the chosen slug/shape/platforms against docs-mcp before locking. See products/README.md.
• Workspace. {doc_workspace} is {project-root}/docs/juspay/ (create it if absent). Artifacts produced here: prd.md, addendum.md, .decision-log.md, plus transient review-*.md / reconcile-*.md. jp-architecture and jp-executor read from this same folder.
• No config of our own. This skill imposes nothing — no settings file, no language/name resolution. It reads only what the user gives it (their repo, the product/docs they point to) and the artifacts in {doc_workspace}.
• Split-repo aware. FE and BE may live in separate repos. Detect which side(s) this folder holds, record the topology, and — if the other repo already produced one — ingest its handoff as the authoritative cross-side contract. See references/split-integration.md.
• Stage tracking. This skill owns the prd funnel phase (the setup phase is emitted earlier by the juspay-cli, at agent-config time — don't emit it here). Emit prd with juspay_track_integration_stage at the points called out in On Activation and Finalize — fire-and-forget, never blocking. See references/integration-stage-tracking.md.

On Activation

0. Connect to the merchant FIRST — before any question, before the codebase scan. Your very first action in this skill is to attempt juspay_get_merchant_details (it takes no arguments). In a launcher-provisioned session the dashboard MCP (juspay-mcp) is already authenticated, so the call just works — do NOT ask whether the user has dashboard access, and do NOT ask which Juspay product they want, before you've tried this call.

• Returns data → CONNECTED. Record merchant_id, client_id (default = merchant_id), and integrationType — the live products on the account (PP = HyperCheckout, EC_API = Express Checkout API, EC_SDK = Express Checkout SDK). This is ground truth for the whole session: you already know what they run, so confirm against it in Product selection — never present a blind product menu. Log it (provenance mcp) in .decision-log.md.
• The tool isn't available, or the call errors → MANUAL mode. Only then may the access question be asked; fall back per references/juspay-mcp.md. Never block.
• Emit funnel entry. Right after the connect attempt resolves, fire-and-forget juspay_track_integration_stage(phase="prd", status="started"). (The setup milestone was already emitted by the juspay-cli at agent-config time — do not re-emit it here.) On a resumed in-progress PRD, skip this (already emitted this session). Do not mention this to the user. See references/integration-stage-tracking.md.

1. Briefly orient the user: this skill produces a Juspay integration PRD, and they can ask you at any point to go deeper on a section (inline advanced elicitation) or weigh a decision from multiple perspectives. On the first message, scan for misroute: technical how / integration design → jp-architecture; actually writing the integration code → jp-executor — suggest the other skill before continuing.
2. Detect intent: Create (no PRD), Update (existing PRD), Validate (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, check {doc_workspace}/prd.md for a prior in-progress PRD (frontmatter status not final); if present, offer to resume rather than starting over.
3. Incoming handoff check. Look for a {doc_workspace}/handoff-<this_side>.md (or a path the user offers) produced by the other repo's run. If present, load it and treat its Cross-Side Contract as authoritative — the PRD for this side must conform to it (don't redesign the seam). See references/split-integration.md.

Intent Modes

Create. Use {doc_workspace} = {project-root}/docs/juspay/ (create if absent). Write prd.md with YAML frontmatter (title, status, created, updated — created/updated = today's date, initial status: draft; plus topology, this_side, other_side from the topology scan — see references/split-integration.md), and create the .decision-log.md skeleton in the workspace so subsequent decisions land in a known file. Tell the user the path. Run ## Discovery, then ## Finalize.

Update. Reconcile the PRD with a change signal. Source-extract against PRD, addendum, .decision-log.md, and original inputs (extract, don't ingest). If .decision-log.md is missing, reverse-engineer a thin log from the PRD before continuing. Surface conflicts with prior decisions before applying. Then ## Finalize.

Validate (or analyze). Critique without changing. Load references/validate.md.

Discovery

Order: (On-Activation connect already ran) → Brain dump → Codebase + env scan → Product selection → Working mode → mode-scoped work. Get to working mode fast — a few turns, not ten. Users in a hurry must not be held hostage by upstream probing. The merchant connection happened in On Activation step 0 — so by the time you reach Product selection you already know what the account runs, and you confirm, never ask blind.

Brain dump. Always the first move, even when the user opens with paragraphs of context. Ask for verbal context and any existing inputs they want you to read — product brief, existing integration notes, prior PRD draft, design docs, the target codebase. Paths or paste; big docs are fine, you will extract. A simple "anything else?" surfaces what they almost forgot.

Codebase + env scan. Read the target codebase and environment to ground the PRD in reality — do not ask for what you can detect:

• Stack & surfaces: language/framework, package manager, backend vs frontend presence, mobile vs web (signals like package.json, pubspec.yaml, requirements.txt, go.mod, AndroidManifest.xml, *.xcodeproj, index.html).
• Topology (split-repo check): classify which side(s) this folder holds. If the chosen product needs both BE and FE but only one is present, this is a candidate split — surface it (genuinely split repos / monorepo sibling / other side not started yet all resolve to topology: split for this run, building only the present side). Record topology (single-repo | split), this_side (backend | frontend | fullstack), other_side (backend | frontend | none). Detailed rules in references/split-integration.md.
• Existing payment code: any current payment/order/checkout handling, webhook routes, order/payment DB schemas.
• Environment: .env/config files for existing provider config, environment/host selectors, secret-management style — never read or echo secret values, only note which keys exist. Production is enforced — record production as the target environment in the PRD's Environments section; don't ask the user to choose sandbox vs production, and note a non-production environment only if the user explicitly and unpromptedly requests it. Reflect what you found back to the user for confirmation.

Merchant access (juspay-mcp). Already handled in On Activation step 0 — reuse its result (mode + merchant_id / client_id / integrationType); do not re-call juspay_get_merchant_details and do not re-ask. The only work left here: if step 0 landed in manual mode (tool unavailable) and identifiers are still needed, gather them now — user-provided, or marked to confirm in the dashboard — per references/juspay-mcp.md. If step 0 was connected, you already have everything; go straight to Product selection. Never block.

Record the chosen mode and each value with its provenance (mcp | user | manual-dashboard) in prd.md and .decision-log.md so jp-architecture and jp-executor reuse it. Only dashboard read calls belong here; credential provisioning happens in jp-executor.

Product selection. Branch on what we already know — never present a hardcoded menu, and never propose products the account doesn't have:

• Connected with a non-empty integrationType → ground the choice in the account. State the MID and the live integrations mapped to readable shapes (PP → HyperCheckout, EC_API → Express Checkout API, EC_SDK → Express Checkout SDK), then choose based on how many products the account has. One integration → don't ask: state it and proceed (e.g. "Signed in as <MID>; your account runs HyperCheckout, so that's what we'll integrate here."). More than one → combine with the codebase signal and infer-and-confirm, offering only the account's own integrations to pick among (e.g. "…your account has Payment Page + EC API + EC SDK and this repo looks like <web/backend>, so I'm assuming EC SDK — right?"). Never offer a "something else / add a new product" choice or surface a product outside integrationType. If the user asks for a product their account doesn't have, tell them it's not enabled on their account and they need to contact Juspay to enable it before it can be integrated — don't scope or build a product the account can't use.
• Otherwise (empty/absent integrationType — new merchant, manual mode, or no MCP) → converge from the catalog + docs, driven by the user's goal: 0. Read products/ first — When to recommend / Intent signals / What it is to shortlist 1–3 candidates (orientation only; see products/README.md).
  1. list_products(category?) to browse the live catalog when the shortlist is inconclusive.
  2. Converge with the user on the product(s) the integration targets.

Confirm via docs-mcp (both branches): explore_product(slug) for the chosen product's doc index (reconcile slug/shape/platforms against it), then doc_fetch_tool(url) on the pages that define credentials, request/response fields, error codes, and webhook structure. Extract what the PRD needs to be grounded (not to generate code): the Glossary vocabulary, the capabilities and constraints that shape FRs, the error/edge surface, and the integration shape (hosted page / headless SDK / direct API). Tag each extracted fact with its source URL.

The integration is payment-method agnostic — which methods a merchant enables is dashboard/runtime configuration, not a PRD-time choice — so don't ask the user to pick payment methods.

Elicitation, not direction. Discovery pulls the user's vision out; it does not insert yours. Open-ended "tell me about X" beats multiple choice. When you find yourself naming MVP cuts or proposing phases, stop — hand the pen back. Infer-and-confirm ("I'm assuming v1 is web checkout only, no mobile surface — right?") is fine. If the user wants a section explored more deeply or weighed from multiple angles, do that inline.

Working mode. Offer the choice in the user's language, using the runtime's native choice UI if available:

• Fast path — I batch remaining gaps into one or two consolidated questions, then draft the full PRD with [ASSUMPTION] tags where I inferred. You review and we iterate.
• Coaching path — we walk PM-thinking sections together. Once chosen, I ask which entry point fits: Capabilities + Flows (capability-first — for most integrations, backend/server work, internal tools) or Journey-led (payer/merchant-experience-first — for consumer checkout, UX-heavy flows). The chosen entry sets the section order.

The workspace persists; stop and resume freely.

Concern scan. As you read what the user gave you, name the integration concerns that actually matter here — webhook/signature handling, idempotency, order reconciliation, go-live gating, platform/SDK surface, public API contracts, tenancy/config isolation, observability, rollback/fallback, and data storage boundaries. These concerns drive which template sections to pull in from the Adapt-In Menu and which to invent when no cluster names them.

Form-factor. If not detected from the codebase, probe — mobile / web / desktop / multi-surface / server-only / API.

Key integration flows are captured, not authored. When journeys are warranted (consumer checkout, merchant-operated flows, meaningful UX), prompt the user to narrate a real session — what triggers the flow, what system calls happen, what the payer/operator sees, and how completion is confirmed — then structure the answer into UJ-N form and confirm. For server-only or API-only integrations, compress this to lean flow descriptions. No standalone persona section.

PRD Discipline

Shape. Capabilities grouped; FRs nested with globally numbered stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. Keep the document close to the integration: products, methods, surfaces, flows, request/response expectations, error surfaces, reconciliation behavior, environment behavior, and explicit boundaries. SDK/API mechanics that are too detailed for the PRD live in addendum.md or get decided in jp-architecture. Treat assets/prd-template.md as expert prior knowledge, not a checklist. The Essential Spine is the expected default — present it unless the integration genuinely doesn't need a section. The Adapt-In Menu is conditional: pull in the clusters the integration's concerns need. When the integration carries a concern the menu doesn't name, invent the section — name it well, place it where it serves the reader. Reorder and combine for readability.

Ground in docs, not memory. Glossary terms, capability constraints, error surfaces, and integration shapes come from the docs-mcp extracts (or the user), cited by URL. Never assert a Juspay field name, endpoint, or behavior from training data.

Length scales with integration complexity. Small single-surface integrations can stay short. Multi-method, multi-surface, or webhook/reconciliation-heavy integrations should expand as needed. Detail that doesn't earn its place in the PRD's main narrative belongs in addendum.md.

Reviewer Gate

Used by the Validate intent and at Finalize step 3.

Assemble the menu: a rubric walker against assets/prd-validation-checklist.md (the PRD quality rubric) + any ad-hoc reviewers the artifact warrants (for example, an integration-flow or error-handling reviewer when the artifact is complex). Keep the review proportional to integration complexity.

Dispatch entries as parallel subagents against prd.md (and addendum.md if present). Each writes its full review to {doc_workspace}/review-{slug}.md and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. The rubric walker uses the prompt and output format in references/validate.md. If subagents are unavailable, run sequentially: write the file before anything else, then flush the review from working context.

Surface findings tiered, never dumped. Lead with a one-sentence gate verdict, then walk critical + high findings; medium/low roll into a single tail ("plus N more in {file}"). Per finding: autofix, discuss, defer to open items, or ignore.

Under Validate intent, the parent additionally runs the synthesis pipeline in references/validate.md — folding every selected reviewer's output into a single HTML + markdown report and opening the HTML.

Finalize

Tell the user the sequence in one sentence, then walk it. Polish goes last so it does not redo work after reviewer fixes.

1. Decision log audit. Walk .decision-log.md with the user; each entry captured in PRD, in addendum, or set aside.
2. Input reconciliation. Subagent per user-supplied input (and per docs-mcp doc set) against prd.md + addendum.md. Each writes its extract to {doc_workspace}/reconcile-{slug}.md and returns ONLY a compact summary (input name, gaps 2-5, file path). Surface gaps — especially qualitative ideas (tone, error-handling expectations, reconciliation rules) the FR structure silently drops. Must happen before polish.
3. Reviewer pass. Run ## Reviewer Gate. Resolve before polish.
4. Triage open items. All Open Questions, [ASSUMPTION] tags, [NOTE FOR PM] callouts. Phase-blockers (would make the PRD unsafe for architecture/executor) surfaced one at a time and resolved; non-blockers deferred with owner + revisit condition logged to .decision-log.md.
5. Polish. Structural passes before prose. Parallelize across documents, sequential within.
6. Close. Set prd.md frontmatter status: final and updated to today's date. Record finalization to .decision-log.md. Then fire-and-forget juspay_track_integration_stage(phase="prd", status="completed", product=<slug>, platform=<surface>, framework=<app framework>) — fill product/platform/framework from the decision log where known, omit what isn't; never block on it (see references/integration-stage-tracking.md). Share artifact paths. Common next: jp-architecture (integration design), then jp-executor (implementation).