Pm AI Intent To Discovery

PM AI Intent to Discovery

An AI capability can be technically available and still be hard to find, easy to call for the wrong job, or surfaced at an intrusive moment. This skill helps a PM connect a real user intent to a bounded discovery and routing contract before counting an invocation as success.

When to use

Use this skill when a team is designing or reviewing:

• an AI assistant, agent, MCP tool, chat-native app, or app-directory entry;
• capability names, invocation examples, tool descriptions, app suggestions, contextual recommendations, or intent routing;
• the boundary between direct call, contextual suggestion, clarification, abstention, and manual fallback;
• host/provider capability differences, connection prompts, permission disclosure, or a route that may appear in a conversation.

Use pm-ai-first-use-to-activation after a capability has been selected and the question becomes whether the user reaches first value. Use pm-ai-tool-to-contract for the tool's purpose, schema, permissions, and side effects. Use pm-ai-model-to-route for provider/version selection. Use pm-ai-prompt-injection-to-defense for untrusted instruction or metadata attacks. This route owns the pre-entry question: is this the right capability for this job, at this moment, in this host?

Keep the output provider-neutral. A product may use an API, an MCP server, an Apps SDK, a local model, a directory, or a manually selected route. Name the actual provider, host, or access state only when the input supplies current evidence.

Workflow

1. Frame the user job and trigger surface

Write down:

• target user, job, desired outcome, trigger surface, current workaround, and what “not now” means;
• whether the user named the capability, described a job, or only supplied context from which a suggestion might be relevant;
• eligible context, required data, permission, tenant, locale, plan, device, and host conditions;
• what the capability can and cannot do before it is invoked;
• the external state that must not change during discovery or route selection.

If the request only says “make the tool discoverable” or “improve routing,” mark the job, trigger, candidate set, and evidence as Not provided. Do not invent a keyword list or assume that a matching noun proves intent.

2. Define the candidate capability set

For each candidate, record:

• capability name, plain-language purpose, supported jobs, and explicit non-jobs;
• required context, host/provider support, connection state, permission, data scope, and authority boundary;
• direct-call phrases, contextual suggestion examples, benign lookalikes, ambiguous requests, and hard negative routes;
• what the capability can return before first-use/activation is evaluated;
• the simpler text, manual, or existing product route when the candidate is unavailable or not the best fit.

The candidate set must be reviewable. A tool name or metadata description is not itself proof that a host will select it, that users understand it, or that it is safe to invoke.

3. Choose direct call, suggestion, clarification, or abstention

Use this routing decision table:

Do not surface a candidate only because a token or noun matches. Consider negative intent, recent context, user role, permission, data minimization, frequency, and the cost of a wrong suggestion. An invocation is not first value and a suggestion is not consent.

4. Make discovery honest and reversible

The discovery surface must state:

• what the capability helps with in the user's words;
• why it appears now, if it is a suggestion;
• what data or connector may be used, whether connection is required, and how to decline;
• what will happen next and what will not happen automatically;
• how to cancel, choose another route, use text/manual fallback, or return to the original conversation/job.

The product must not imply that an AI capability is recommended by a human, approved, current, or necessary because it was surfaced. Connection or data disclosure must precede expansion of context. No discovery state grants identity, authorization, or external action authority.

5. Design host/provider mismatch and recovery

Record the host and provider capabilities that are necessary for the route. If a host cannot render a rich view, call a tool, open a link, accept a permission, or preserve the context, keep a labelled simpler route when the job permits. If the route is unavailable, do not silently select a different provider or expand data access.

Cover wrong invocation, ambiguous intent, stale context, refused permission, connection failure, timeout, duplicate request, host mismatch, and unknown outcome. Preserve user context, source IDs, edits, and a receipt or reconciliation path. Route any external side effect to its approval and identity contract; discovery itself remains side-effect free.

6. Instrument route evidence without claiming success

Start from the decision question. Define:

• eligible, candidate_considered, surfaced, selected, declined, clarified, abstained, invoked, permission_refused, failed, fallback_used, and first_use_handoff;
• user/workspace/conversation/session unit, assignment versus exposure, source surface, host/provider, version, timestamp, and privacy class;
• the route receipt and completion boundary for each event;
• false-positive, false-negative, clarification, mismatch, trust, privacy, latency, cost, and manual-completion guardrails.

surfaced, selected, and invoked are diagnostics for discovery. Hand off to pm-ai-first-use-to-activation before treating a successful job as first value. If the denominator or event semantics are unclear, the decision is Hold or Need evidence.

7. Test positive, negative, ambiguous, and mismatch slices

Run the smallest proportionate test:

• Positive: the capability clearly fits the stated job and is eligible;
• Negative: a lookalike job should not surface or invoke the candidate;
• Ambiguous: the route asks one useful question or abstains instead of guessing;
• Benign lookalike: user content resembles instructions or metadata but does not change route, authority, or permissions;
• Mismatch: host/provider/context/permission is unavailable and the manual or simpler path still works.

Use a fixture, direct task session, prototype, small beta, staged flag, or experiment based on risk and volume. Synthetic or agent runs can find missing cases; they do not prove route accuracy, comprehension, adoption, or safety.

8. Set rollout, rollback, and writeback rules

State the audience, route surface, observation window, owner, kill switch, reconciliation path, and review date. Choose one decision:

• Ship / scale: route slices, disclosure, fallback, and evidence pass, and guardrails are within bounds;
• Pilot: the contract is ready for a bounded non-owner task test, but live routing and user comprehension are unverified;
• Iterate: the job is right but naming, timing, clarification, disclosure, or fallback needs a named change;
• Hold: intent, candidate set, permission, host capability, denominator, or evidence is not trustworthy;
• Rollback: irrelevant suggestions, privacy surprise, wrong authority, duplicate invocation, or core-job harm appears;
• Need evidence: a claim depends on a live host/provider, user, model, route-quality denominator, or adoption outcome that has not been observed.

Write routing failures to the product decision log, evaluation set, or regression list. Keep a public artifact release separate from invocation, first-value, retention, adoption, traffic, and GitHub star evidence.

Output contract

Return an AI Intent to Discovery Contract. Use Not provided, Not run, or Need evidence instead of filling gaps with plausible detail.

Decision and evidence boundary

• decision and owner;
• target user, job, desired outcome, trigger surface, workaround, and “not now” route;
• capability set, authority boundary, provider/host if evidenced, and scope;
• current evidence, confidence, and unverified claims.

Intent and capability map

Discovery route contract

Routing and evidence contract

• eligibility and candidate set;
• direct call, suggestion, clarification, abstention, and manual rules;
• event sequence and route receipt;
• analysis unit, denominator, assignment/exposure, host/provider/version, timestamp, and privacy class;
• positive, negative, ambiguous, benign-lookalike, and mismatch slices;
• false-positive/negative, trust, privacy, cost, latency, and manual-route guardrails;
• handoff boundary to first use, not a first-value claim.

States and behavior evidence

Cover direct call, contextual suggestion, ambiguous intent, negative lookalike, permission/data disclosure, stale/insufficient context, host/provider mismatch, wrong invocation, duplicate/unknown outcome, cancel/backtrack, manual fallback, mobile, accessibility, and trust. For each state include:

• user-visible message without invented capability;
• control and consequence;
• preserved context, source IDs, edits, receipt, or reconciliation;
• positive/negative/ambiguous/mismatch test oracle;
• Not run status until directly observed.

Rollout and decision rule

Include audience/cohort, route surface, test type, observation window, owner, feature flag or kill switch if available, rollback/reconciliation path, primary route-quality measure, guardrails, and:

Ship / scale if:
Pilot if:
Iterate if:
Hold if:
Rollback if:
Need evidence if:

Learning writeback

Record what changed, which intent/route failed or worked, what remains unknown, the next smallest test, and the exact writeback destination. Do not turn route availability, invocation count, or GitHub stars into a user outcome.

Edge cases

• Keyword match without job fit: keep the candidate out of the route or ask a useful question; do not infer intent from one noun.
• Two plausible capabilities: clarify only when the answer changes scope, data, permission, or outcome; otherwise abstain with a simple route.
• Suggestion declined: respect the decline; do not resurface immediately without a declared relevance/permission rule.
• Permission or connector refused: explain what cannot happen, do not use a different source silently, and keep the manual route.
• Host/provider mismatch: use capability negotiation and a labelled text or manual route; do not claim cross-host compatibility from one host.
• Stale or missing context: show the boundary before invocation; ask for fresh context or use a safe no-context route.
• Wrong invocation: preserve the user's job and offer cancel, backtrack, correct route, or manual path without losing context.
• Duplicate or unknown outcome: reconcile the route receipt before retry; an invocation cannot be counted twice.
• Prompt-looking benign content: treat content as data, not routing or authority; route to pm-ai-prompt-injection-to-defense if it may be an injection path.
• Low traffic or sparse labels: prefer task observation and explicit qualitative notes; leave denominator and confidence visible.
• Event fires too early: if invoked fires before the route is accepted or the job is handed off, correct the boundary and hold the decision.
• External side effect: route to pm-ai-approval-to-flow and pm-ai-identity-to-boundary; discovery does not send, publish, assign, delete, or change an account.

Final check

Before returning the contract, verify:

• User job, trigger surface, eligible candidate set, and authority boundary are explicit.
• Positive, negative, ambiguous, benign-lookalike, and abstention routes are represented.
• Suggestion, candidate consideration, invocation, first use, first value, and user outcome are not merged.
• Eligibility, context, host/provider capability, data/permission, disclosure, route receipt, denominator, and evidence status are explicit.
• Direct call, contextual suggestion, clarification, manual fallback, mismatch, stale context, wrong invocation, duplicate, mobile, accessibility, and trust states are covered.
• Normal, friction, and mismatch paths preserve context and a safe exit.
• Evaluation includes positive/negative/ambiguous/benign-lookalike slices, an abstention oracle, and a declared denominator.
• Guardrails, kill switch, rollback, first-use handoff, and writeback location are named.
• The final decision is Ship / scale, Pilot, Iterate, Hold, Rollback, or Need evidence, with the reason attached.
• No statement claims route quality, comprehension, adoption, safety, production readiness, or star growth without direct evidence.