# Skill Card — Suede Recommend Next Action

<!-- Generated by scripts/build-skill-cards.mjs — do not hand-edit. -->
<!-- Regenerate with: npm run build:cards -->

Release record for the `suede-recommend-next-action` skill, following the NVIDIA skill-card template (<https://docs.nvidia.com/skills/skill-cards>). It tells a reviewer what the skill does, who owns it, what it needs, what could go wrong, and what evidence backs the release — without requiring them to open the source first.

## Description

Next-action selector for the Suede pack: inspects current repo, terminal, plan, or handoff state read-only and returns one recommended next move plus a short, self-contained copy/paste prompt for it.

Status: production. Ships in the `suede-skills` plugin (the full pack) at release 0.19.0; loads as a Claude Code / Codex agent skill from this directory's [SKILL.md](./SKILL.md).

## Owner

Jason Colapietro, Suede Labs AI (<https://github.com/JasonColapietro>). Security contact: `info@suedeai.ai` per [SECURITY.md](../../SECURITY.md).

## License / Terms of Use

MIT ([LICENSE](../../LICENSE)). The pack's combined license expression is `MIT AND BSD-3-Clause`; this skill bundles no third-party licensed material of its own.

## Use Case

Target users: developers and creators running the skill inside a Claude Code or Codex CLI session.

Use when the user asks 'what's next', 'what should I do next', 'recommend the next move', 'give me the prompt', 'expand prompt', or 'make it granular', especially after a review, audit, plan, or stalled task.

Out of scope — executing the recommended action without the user's separate authorization, or coordinating a multi-lane build across specialists (use suede-agent-teams).

## Deployment Geography

Global. The skill is a prompt-and-script package that runs locally inside the invoking agent session; it pins no region-specific service of its own.

## Requirements / Dependencies

- A Claude Code or Codex CLI session with the `suede-skills` plugin installed (install options: <https://skills.suedeai.ai/>).
- Bundled files loaded relative to this directory: `agents/` (1 file), `references/` (1 file).
- Credentials: none are bundled or required by the skill files. Any tool or API credentials come from the host session; never paste credentials into skill files, prompts, or outputs.

## Known Risks and Mitigations

- Risk: an agent treats a quality gate as autonomous authority. Mitigation: every gate in the pack is advisory — it changes what is reported, never what the user decided; only extreme-risk findings (data loss, credential exposure, legal/rights violations, payment mistakes, irreversible public damage) pause for the user's explicit choice.
- Risk: a skill instruction is used to act outside its mandate. Mitigation: the hard limits in the skill body's "Boundaries" section, quoted below.

From "Boundaries":

- Do not mutate files, repos, deployments, accounts, messages, or live systems while recommending.
- Do not load the expanded or granular prompt by default.
- Do not repeat a broad audit when one current execution lane can be selected.
- Do not invent paths, URLs, skill availability, status, metrics, owners, or completion evidence.
- Do not recommend vague actions such as "keep working", "improve the app", or "do more research". Name a command, artifact, decision, edit, or verification result.
- Do not hide a blocker. If authority or a decisive fact is missing, make its resolution the next action.

## References

- Skill source: [`skills/suede-recommend-next-action/SKILL.md`](./SKILL.md)
- Rendered reference page: <https://skills.suedeai.ai/skills/suede-recommend-next-action.html>
- Security policy and reviewed scanner exceptions: [SECURITY.md](../../SECURITY.md) and [`.plugin-scanner.toml`](../../.plugin-scanner.toml) at the repo root

## Skill Output

Structured Markdown returned in the agent's response, shaped by the output contract defined in the skill body: "Output Format". The skill publishes, posts, and sends nothing without the user's explicit authorization; delivery decisions stay with the user.

## Skill Version

0.19.0 — the pack is single-versioned, so every skill releases together; see [VERSION](../../VERSION) and [CITATION.cff](../../CITATION.cff) for the release identifier this card describes.

## Ethical Considerations

- The skill produces recommendations for a human decision-maker. Publishing, sending, payment, and rights decisions stay with the user.
- Its gates require verifiable claims and honest reporting; do not use the skill to fabricate claims, evidence, metrics, or attribution.
- Report suspected misuse or a security concern privately per [SECURITY.md](../../SECURITY.md); do not open a public issue for it.

---
name: suede-recommend-next-action
description: "Next-action selector for the Suede pack: inspects current repo, terminal, plan, or handoff state read-only and returns one recommended next move plus a short, self-contained copy/paste prompt for it. Use when the user asks 'what's next', 'what should I do next', 'recommend the next move', 'give me the prompt', 'expand prompt', or 'make it granular', especially after a review, audit, plan, or stalled task. NOT FOR: executing the recommended action without the user's separate authorization, or coordinating a multi-lane build across specialists (use suede-agent-teams)."
---

# Suede Recommend Next Action

Recommend one action and package it as a short runnable prompt. Inspect
current state read-only; do not execute the recommended action unless the
user separately authorizes execution. Keep the full operator contract hidden
until the user asks to expand it.

## Recommendation Workflow

1. Resolve the target and the user's actual done outcome from the current
   request, conversation, handoff, plan, repo, or live surface.
2. Check only the evidence needed to distinguish the next move. Prefer, in
   order: current terminal/repo/live state, current source documents, current
   plans or handoffs, then older memory. Run the reads, don't assume them:
   `git -C <target-repo> status --short --branch` for dirty files and
   ahead/behind, `git -C <target-repo> log --oneline -5` for what actually
   landed, a direct read of the named plan/STATE/handoff file at its exact
   path, and — when a live surface is in scope — a fetch of the URL itself
   (`curl -sS -o /dev/null -w '%{http_code}' <url>`) instead of trusting the
   last recorded deploy. Skip any read that cannot change which candidate wins.
3. Generate 2-4 candidate actions internally. Exclude work already verified as
   complete, adjacent cleanup, and actions outside the user's authorized scope.
4. Score each candidate from 0-2 on every criterion below. Recommend the
   highest total.

| Criterion | 2 points | 1 point | 0 points |
|---|---|---|---|
| Goal alignment | Directly produces the user's done signal | Required prerequisite | Merely adjacent |
| Unblocking | Unlocks a core path or at least two downstream steps | Unlocks one step | Unlocks nothing known |
| Evidence | Confirmed by current source | Confirmable with one read-only check | Depends on an assumption |
| Urgency | Active failure, deadline, security risk, or release gate | Needed for the active milestone | No current pressure |
| Leverage | Fits one focused session and prevents rework or creates a reusable result | Bounded work with moderate payoff | Unscoped, multi-day, or low-payoff work |

5. Break ties by preferring a required prerequisite, then current-evidence
   verification, then the more reversible action. If the top two remain within
   one point and target ambiguity would change the answer, run at most three
   additional read-only checks. If still tied, show both choices and state the
   single fact that decides between them.
6. Turn the recommendation into a 2-4 sentence quick prompt. Keep the scoring
   and full operator contract internal unless the user asks to compare choices,
   `expand prompt`, or `make it granular`.

## Routing Rules

- If a repo or task already has its own plan, progress doc, issue tracker, or
  project board, do not create a second one. Treat its recorded next step as
  one candidate, verify it against current source, and recommend the winner —
  don't replace the existing tracker.
- If the user needs options explored before a commitment can be made, say so
  and offer to brainstorm instead of forcing a single recommendation.
- If missing evidence is the real blocker, make the smallest read-only check
  the recommended action and generate a prompt for that check.

## Prompt Levels

The three prompt depths — short copy/paste, full operator prompt, granular steps —
are in `references/prompt-levels.md`. The default is the short prompt; read this
only when the user asks to expand or make it granular.

## Output Format

```text
Recommended action: <one sentence>
Why now: <one evidence-backed sentence>

Quick prompt: <2-4 runnable sentences>

Say "expand prompt" for the full operator version or "make it granular" for exact steps and commands.
```

Show the route, score, evidence list, confidence, or alternatives only when the
user asks for rationale or when the unresolved tie rule requires them. When the
recommendation is an evidence-gathering step, state that in `Why now` without
loading the expanded prompt.

## Boundaries

- Do not mutate files, repos, deployments, accounts, messages, or live systems
  while recommending.
- Do not load the expanded or granular prompt by default.
- Do not repeat a broad audit when one current execution lane can be selected.
- Do not invent paths, URLs, skill availability, status, metrics, owners, or
  completion evidence.
- Do not recommend vague actions such as "keep working", "improve the app", or
  "do more research". Name a command, artifact, decision, edit, or verification
  result.
- Do not hide a blocker. If authority or a decisive fact is missing, make its
  resolution the next action.

## Routing

- Need multi-lane coordination across specialists -> use `suede-agent-teams`.
- Need help picking which single skill fits a request -> read this pack's
  router (`suede-workflow-skills`) or ask directly.
- Need idea exploration before selecting a move -> brainstorm directly with
  the user instead of forcing a single recommendation.
- Need execution -> use the specialist named in the generated prompt.