connect-recommend

# Connect Recommend

Recommend the right Stripe Connect integration shape. The user should only need to provide a company URL or describe their business — the skill figures out the rest.

## Interaction Model

**AskUserQuestion is the primary interaction tool.** Every decision point in this skill MUST use AskUserQuestion with clear, numbered options and short descriptions. One question at a time — never overwhelm the user.

**Auto-act on low-cost actions.** Never ask permission for:
- Generating the markdown recommendation plan — just generate it
- Scanning the codebase — just scan it
- Reading reference files — just read them

**Never end with passive text.** Every stopping point must end with an AskUserQuestion offering concrete next actions.

## Terminology rules (user-facing output)

**Before generating any user-facing output, read `references/terminology-rules.md`.**
Apply those rules to all recommendation text, warnings, explanations, and decision summaries.

Key principle: describe configurations using field values (dashboard + fee ownership + negative balance liability ownership + charge pattern), not shorthand codes.

## Output Brevity

Keep responses concise. The user is making decisions, not reading documentation.

- Lead with the recommendation, follow with brief rationale
- Technical details (API paths, capability checks) go in a "Details" section of the final markdown plan — not inline in the main recommendation
- Warning blocks: 2-3 sentences maximum. State the issue and the fix. No mechanism deep-dives unless the user asks.
- Decision summary: bullet points only, one line per decision
- Never output more than ~40 lines in a single response during interactive mode

**Only surface out-of-scope limitations when they are directly relevant to what the user asked about.** Do not proactively list constraints or unsupported features (e.g., OAuth, international expansion) when the user has not asked about them. "Out-of-scope" here means outside what this guide supports, not outside what Stripe supports. Research these topics in Stripe's public documentation (docs.stripe.com) rather than saying they're out-of-scope.

## Instructions

### Step 0 — Show progress

Display the progress checklist so the user knows what to expect:

```
Here's what we'll do:

  [ ] Learn about your business
  [ ] Scan your project
  [ ] Recommend configuration + charge pattern
  [ ] Produce recommendation plan

Let's get started.
```

### Step 1 — Learn about the business (ALWAYS runs first)

This is the most important step. Before scanning any code or asking technical questions, understand **what the business is**.

**1a. Check if the user already provided a URL or business description** in their message. Look for:
- A URL (e.g. `https://...`, `www.`, `.com`, `.io`)
- A business description (e.g. "I'm building a marketplace for...", "We connect freelancers with...")
- A company name that can be searched

**1b. If nothing was provided**, ask immediately using AskUserQuestion — this is the FIRST question the user sees:

```
Tell me about your business. Pick whichever is easiest:
```

Options:
- "I have a URL" — user provides URL, then research it
- "Let me describe it" — user provides description, then research it
- "Just scan my codebase" — skip to Step 2, rely on codebase signals only
- "Skip — ask me questions instead" — skip to Step 3 with full questionnaire

**1c. Research the business** — invoke the company-researcher agent:

Use the `Task` tool with `subagent_type: "general-purpose"` to invoke the company-researcher agent. In your prompt, include:
- The company URL (if provided)
- The business description (if provided)
- Ask the agent to read `agents/company-researcher.md` for its instructions

The agent will return a structured analysis with confidence levels (HIGH/MEDIUM/LOW) for each decision dimension.

**1d. Parse the agent's output** — it returns a Research Findings table with confidence levels per dimension. Read the decision matrix at `skills/connect-recommend/references/decision-matrix.md` and map the findings to a recommended configuration. Then determine pre-fill behavior per dimension:
- **HIGH confidence**: Auto-fill — do not ask about this dimension
- **MEDIUM confidence**: Suggest the inferred value and ask for quick confirmation
- **LOW confidence**: Ask the original open-ended question in Step 3

**1e. Present what you learned** to the user (use second-person, conversational confirmation tone):

```
Here's what I gathered about your business — let me know if anything looks off:
  ┌──────────────────────────┬────────────────────────────────┐
  │ *Business type*          │ [marketplace or SaaS platform] │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Sellers/providers*      │ [who they are]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Buyers/customers*       │ [who they are]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *How money flows*        │ [payment flow]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Fee structure*          │ [fee details]                  │
  └──────────────────────────┴────────────────────────────────┘

Based on this, I'd recommend: [configuration description in plain language]

I'll proceed with this unless you'd like to correct anything.
```

For MEDIUM confidence items, append: "I'm also assuming [X] — sound right?"

If the agent flags "not-connect" (business doesn't need Connect), use AskUserQuestion:

```
Based on my research, your business may not need Stripe Connect — a standard Stripe integration might be a better fit.
```

Options:
- "Proceed with Connect anyway" — continue discovery
- "Explore standard integration instead" — exit this skill, suggest standard Stripe integration

Update the checklist:
```
  [x] Learn about your business
  [ ] Scan your project
  [ ] Recommend configuration + charge pattern