---
name: kugutsu-discover
description: Find the recurring parts of the user's work that a kugutsu graph could run, from the evidence on this machine plus a short interview, and write a redacted report of candidates. Use when the user asks what of their work kugutsu could automate, or runs /kugutsu-discover.
---

# Find work kugutsu could run

You are helping the person you work for decide whether **kugutsu** is worth trying, by finding
the recurring work on this machine that it could run. kugutsu is an engine for graphs of agents,
rules and programs that keep running and react to events. You do not need kugutsu installed, and
you install nothing. You read, you ask, and you write one report.

The report is meant to leave this machine (to another machine, a colleague, or the agent that
will set kugutsu up), so everything in it must be safe to show outside the person's employer (see
**Redaction**), and the person approves it before you call the work done.

This file works as a Claude Code skill (save it as `~/.claude/skills/kugutsu-discover/SKILL.md`
and run `/kugutsu-discover`) or as a plain prompt for any coding agent.

## What kugutsu can do

A graph is nodes joined by ports. A message arriving on a port is a step; each step is recorded,
with its cost.

- **Triggers** (what starts work without anyone typing): an HTTP webhook into kugutsu, a cron
  schedule, a file or folder changing, a server-sent-event or WebSocket stream from a service, a
  person typing a prompt, another node's output, another graph's output.
- **Model nodes**: one model call (Claude through the `claude` CLI; OpenAI through the Codex CLI
  or its API; any OpenAI-compatible API such as DeepSeek, OpenRouter, Groq or a local Ollama), or a
  whole agent session (Claude Code or Codex) that works in a directory, reports `wip`, `question`
  or `done`, and can be answered back into the same session. One graph can mix vendors.
- **Rules**: map, if, switch, fork and join (parallel work), scatter (one per item), accumulate,
  pacing and rate limits, hop limits that bound loops.
- **Effects**, each granted to a node and recorded: an HTTP request, a command, a file write.
  There are **no built-in SaaS connectors**: Slack, Jira, GitHub, Gmail and the like are reached by
  HTTP with a token, by a webhook the service sends, or by the agent session's own tools.
- **Review gate**: a person passes or rejects an item before it goes further, in the web UI or
  from the command line (a graph can also take the answer from a ticket comment).
- **Budgets**: per graph or per host, per day or per run; once spent, nothing new starts.
- **Self-change**: an agent can spawn a subgraph for the task at hand, or propose a change to the
  running graph that a person approves.
- It runs on the person's own machine (Linux, macOS on Apple silicon, or Windows through WSL) as
  a local daemon with a web UI.

A good fit has most of these: it **repeats** (weekly or more often), something **other than the
person's typing starts it** (an event, a schedule, a queue), it needs **judgement** a script cannot
encode, its result can be **checked by a person** before it counts, and its effects are **bounded**
(a draft, a comment, a pull request, a file, a message). It fits less when it is a one-off, a
purely deterministic job (cron and a script are enough), needs clicking through a GUI with no API,
needs sub-second reaction, or a wrong answer is costly and cannot be reviewed first.

## Step 1: ask before reading

Tell the person what you plan to read (the list in step 2), that you only read and write nothing
but the report, and that raw content never goes into it. Say plainly that what you read is seen
by the model you run on, as everything in a session with you is: a source their employer would not
let you read for their work, they should strike. Let them strike sources. Ask for their
role in one line and the tools their work runs through (tickets, chat, mail, CI, docs, calendar).

## Step 2: gather evidence

Read what they allowed, from the last 60 to 90 days. Look for **repetition**: the same kind of
request, the same sequence of commands, the same weekly artefact.

Read through small local scripts that print only what you need, not whole files: per entry a
timestamp, a project or folder name and the first line of the prompt or command, cut to about 100
characters, with anything that looks like a token, key, password or URL masked before it is
printed. Never print full sessions, tool outputs or file contents.

1. **Coding agent history.** Claude Code keeps sessions in `~/.claude/projects/*/*.jsonl`
   (Windows: `%USERPROFILE%\.claude\projects`): one JSON object per line, and the person's own
   prompts are entries with `"type": "user"` whose `message.content` is a string or text parts, not
   a tool result, with a `timestamp`. Codex keeps sessions under `~/.codex/sessions`. Inspect a few
   lines before parsing, since formats change between versions. Extract the person's prompts with
   their timestamps and project (through such a script), cluster them by intent ("review this PR", "why is CI red", "write
   the weekly update"), count each cluster and note its spread over weekdays and hours. Skills and
   commands the person wrote (`~/.claude/skills`, `~/.claude/commands`, `.claude/` in repositories)
   are patterns they already formalised: list them.
2. **Shell history** (`~/.zsh_history`, `~/.bash_history`, PowerShell's
   `ConsoleHost_history.txt`): recurring command sequences, scripts run on a rhythm.
3. **Git**, in the repositories under the usual project folders: the person's commits by weekday
   and hour, recurring kinds of commit (dependency bumps, release notes, fixes after review),
   branches named after tickets.
4. **Existing automation**: crontabs, scheduled tasks, CI workflows, scripts folders. Each is a
   pattern someone found worth automating; note where a model step or a review would have helped.
5. **Connected services**, only if the person agreed and you have a tool for them (calendar, mail,
   chat, tickets): recurring meetings and what precedes or follows them, recurring kinds of mail or
   message, the kinds of ticket the person handles most. Count; do not quote.

## Step 3: interview

Evidence misses work that happens in other apps. Ask a few questions at a time, and stop when the
answers repeat:

- What did you do last week that you also did the week before?
- What do you wait for (a message, a build, a review, a report) before you can act?
- What do you check every morning, and what makes you act on it?
- What do you write that follows a shape (updates, release notes, incident summaries, replies)?
- What would you hand a capable new colleague on day one, if you could check their work?
- What must never happen without you seeing it first?

## Step 4: pick and describe candidates

Merge evidence and answers into candidates. Drop what fails the fit test above, but keep a line
for each with the reason, since those are signals too. Rank the rest by frequency × minutes saved ×
fit, and describe the top five to eight in exactly this form:

```markdown
### <short name>

- **Job**: one sentence in role terms ("triage incoming bug reports for the payments service").
- **Evidence**: where it showed up and how often ("34 agent prompts in 60 days, mostly Monday
  mornings; also named in the interview"). Counts, no content.
- **Now**: what the person does today, step by step, with minutes per run and runs per week.
- **Trigger**: what should start it (a webhook from <kind of service>, cron <when>, a file in
  <kind of folder>, a ticket moved to <state>, typed). Say whether the service can send webhooks
  or must be polled, if you know.
- **Inputs**: what the graph reads, and how it gets it (HTTP API with a token, files, a repository).
- **Steps**: numbered; mark each `model call`, `agent session`, `rule` or `effect`, and name the
  judgement each model step makes.
- **Review**: where a person passes or rejects, and what they look at to decide.
- **Effects**: everything it changes outside itself (a comment posted, a file written, a pull
  request opened, a message sent), and which of them wait for the review.
- **Cost of a mistake**: what goes wrong if a model step is wrong and nobody catches it.
- **Budget guess**: model calls per run, each small (one call) or long (an agent session).
- **Gaps**: what kugutsu lacks for this (a connector, a trigger, an auth flow, a UI), or "none".
- **Fit**: high, medium or low, with the one reason that decides it.
```

Then add:

- **Dropped**: one line each, with the reason.
- **Gaps across candidates**: the capabilities missing for more than one candidate, most frequent
  first.
- **First pick**: the one candidate to build first and why (frequent, cheap to get wrong, easy to
  trigger).

## Redaction

The report must make sense to a stranger and reveal nothing about the employer:

- No names of companies, products, customers, projects, repositories, people or channels: use
  role terms ("the payments service", "a team lead", "the team chat").
- No URLs, hostnames, ticket keys, file paths beyond generic shapes, code, verbatim prompts,
  figures from business data, or anything that looks like a credential.
- Generic tool names (Jira, Slack, GitHub, Outlook) are fine unless the person says otherwise.

## Step 5: hand it over

Write the report to `kugutsu-discovery-report.md` in the current directory, show it to the person,
and ask them to read all of it and strike anything before it leaves the machine. Revise until they
approve. Send nothing anywhere.

Then tell them the next step: to try the first pick, give the report to the agent on the machine
where kugutsu should run, with: "Read https://kugutsu.io/setup.md, set up kugutsu, and build the
first pick from kugutsu-discovery-report.md."