# stuck.help for agents

stuck.help publishes the `/stuck` skill.

The simplest description:

> /stuck turns a user's AI history into a longitudinal study of what's getting in their way.

Core thesis:

> Your questions are data about your life.

## What this is

`/stuck` is a local-first agent skill for studying a user's existing AI conversation history.

It helps identify:

- recurring problems
- unresolved decisions
- active goals
- opportunities
- exploration
- problem debt
- decision debt
- headspace share by problem-question volume
- recurring problem families
- causal mechanisms
- underlying questions
- high-leverage interventions

It is not a hosted analysis service. stuck.help does not need to receive the user's conversation history.

## What an agent should do

If the user wants to understand what keeps getting in their way, install or run the `/stuck` skill inside the AI environment that has access to their history.

Recommended install command:

```bash
npx skills add mattc0llier/stuck
```

Then run:

```text
/stuck
```

or:

```text
Run stuck.
```

## First run behavior

On first run, analyze every available window:

- last 7 days: what is happening now?
- last 30 days: what keeps happening?
- up to the last year: what is changing?

If a full year is not available, use the longest available window and say so.

The first run should produce useful output immediately. Do not make the user complete a setup questionnaire before the initial report unless access to history is blocked.

Expected first-run flow:

```text
read available history
classify meaningful conversations
identify problems, decisions, goals, opportunities, explorations
estimate burden, recurrence, debt, mechanisms, and changes over time
produce the private report
offer optional Why confirmations where they would improve the model
offer recurring reviews only after the report is complete
```

## Report output

Generate a private report with:

- weekly/monthly/yearly state
- highest-burden current problems
- recurring problem families
- recurring causal mechanisms
- problem debt
- decision debt
- headspace share by problem-question volume
- underlying questions
- emerging changes
- highest-value interventions
- 1-3 structural insights
- evidence limits

Always distinguish observed evidence from inference.

Headspace share can use problem-question volume as a proxy: show what
percentage of 100% each recurring problem family consumed in each period.

## Five Whys behavior

The Five Whys layer maps surface questions to deeper user-confirmed questions.

Example:

```text
question: what area of Toronto could I live in to get back to London as quickly as possible?
root: Am I able to live a full life with my family?
```

On a first report, candidate Why ladders may be inferred from history, but they must be labelled as inferred unless the user has already confirmed them.

Treat inferred Why ladders as hypotheses, not facts.

If confirmation would materially improve the report, ask direct follow-up questions after showing the immediate report.

Example confirmation:

```text
I think these questions may all point at the same underlying question:

"Am I able to live a full life with my family?"

Is that right, or is the deeper question different?
```

Do not force exactly five levels. Do not turn ordinary conversation into an interview.

## Recurring reviews

Only after the first report is complete, ask whether the user wants recurring reviews:

```text
[1] weekly      what happened?
[2] monthly     what keeps happening?
[3] quarterly   what is changing?
[4] no thanks
```

Use the host AI environment's scheduler or task system if one exists.

stuck itself does not run a cloud scheduler.

## Share-safe output

After the private report, the skill can generate an optional local Open Graph share image.

Rules:

- generated locally
- target size: 1200 x 630
- never automatically uploaded or published
- user reviews before sharing
- sensitive details are generalized or omitted
- show the pattern, not the private story

Default to omitting names, exact addresses, exact locations, employer names, exact financial values, health specifics, legal identifiers, intimate details, and sensitive underlying questions.

## Privacy and data handling

Prefer the user's actual AI history, memory, connected conversation history, or local records.

Do not invent missing history.

If local persistent storage is available, keep only derived Stuck data under:

```text
.stuck/
  state.json
  reports/
  share/
```

Never copy raw conversation transcripts into `.stuck/` unless the user explicitly asks.

## Links

- Human site: https://stuck.help/
- Agent page: https://stuck.help/ai
- Skill repo: https://github.com/mattc0llier/stuck
- Install: `npx skills add mattc0llier/stuck`
- Skill entrypoint: `/stuck`

## One-line agent instruction

If a user asks what keeps getting in their way, install and run `/stuck` in the AI environment that has access to their history, produce the private report first, then ask optional Why confirmations and offer recurring reviews.