agentleFS
ArchAstroArchAstro/archdev/tasks-audit/SKILL.md

tasks-audit

Skill4 starsChanged 41 days agoMITView on GitHub

Use when someone wants to go through their own paused, blocked, failed or stuck ArchDev Tasks — find every Task assigned to them that is not moving, work out why from its comments, dependencies and inbox question, explain each reason in plain language, and walk them through answering, unblocking, splitting or cancelling it. Fans the investigation out to subagents, one per epic. Triggers include "audit my tasks", "what's paused", "what's blocked on me", "why is this stuck", "go through my paused tasks", "triage my inbox", or /tasks-audit.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 6 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Explain first, then propose: Every Task in the report says what it is waiting for, in plain language, before any action is offered.

    line 22
  2. Very specific:

    Don't invent reasons: If the Task's metadata.pause, inbox row, comments and dependencies don't say why it stopped, report "no recorded …

    line 28
  3. Very specific:

    Use the archdev CLI for every Tasks operation, with --json for output you parse.

    line 32
  4. Very specific:

    Follow the archdev skill for activity reporting.

    line 38
  5. Distinctive:

    If the user gave an ID or a name, use it.

    line 65
  6. Distinctive:

    If exactly one assignee plausibly matches, use it and say so on the report's first line ("Auditing Tasks assigned to Calvin Grunewald") so …

    line 73
  7. Very specific:

    Keep run state outside the checkout, for example ~/.archdev/tasks-audit/<YYYY-MM-DD>/ (mkdir -p first): me.json, inventory.json, one …

    line 81
  8. Very specific:

    Only is_blocked == true means a Task is waiting on unfinished work.

    line 105
  9. Very specific:

    Every paused Task's reason, when one was recorded, is on the Task itself: metadata.pause (kind, category, blocker, question, recommended, …

    line 109
  10. Very specific:

    Write inventory.json and tell the user the counts per bucket in one line before investigating, so they can narrow the audit ("only the …

    line 141
  11. Distinctive:

    Other harnesses: use their subagent or parallel-task facility with the same brief.

    line 220
  12. Very specific:

    Check what comes back. Spot-check one finding per group against the Task's comments yourself.

    line 225
  13. Distinctive:

    When the audit has more than about 15 Tasks, also offer the report as a page (an HTML artifact, if the harness can publish one): one card …

    line 298
  14. Very specific:

    Run each change, then append it to actions.jsonl with the Task, the command, and the result.

    line 325
  15. Distinctive:

    Every status change gets a comment saying why and what it unblocks.

    line 351

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Audit your paused, blocked and failed Tasks

Find every Task assigned to the user that is not moving, explain why in words they can act on, and help them clear it. The run is a workflow:

connect → who am I → inventory ──→ investigate (subagents, one per epic)
                                         ↓
            finish ← act (approved only) ← walk through ← plain-language report

Rules that hold through every phase:

  1. Read-only until the user approves a specific change. Inventory, investigation and the report change nothing. "Audit my tasks" is not approval to answer, reopen, cancel or retag anything.
  2. Explain first, then propose. Every Task in the report says what it is waiting for, in plain language, before any action is offered.
  3. Don't fight a running Factory. A native status change does not clear a Factory's local state; its overseer re-pauses the Task within minutes. Factory-owned work is unblocked by answering it (tasks answer) or by asking the overseer to resume it, never by tasks update --status open.
  4. Don't invent reasons. If the Task's metadata.pause, inbox row, comments and dependencies don't say why it stopped, report "no recorded reason" and what would find out. Mark guesses as guesses.

Use the archdev CLI for every Tasks operation, with --json for output you parse. The CLI is the authority when it disagrees with this file: read "$archdev" tasks guide once per session.

Activity and risk ownership

Follow the archdev skill for activity reporting. Plan/task lifecycle events retain their risk.plan / risk.task assessments. Server automation owns hosted PR and code-region grading: report PR events without fetching, waiting for, reusing, or attaching a server grade. No local assessment, annotation or stop hold is required.

0. Connect

Resolve the absolute directory containing this SKILL.md and run its bootstrap. It installs or updates ArchDev when the binary is missing or lacks tasks inbox / tasks answer; get approval before installing or upgrading software. Capture stdout, which is the executable's absolute path.

archdev="$(bash /absolute/path/to/tasks-audit/scripts/bootstrap.sh)"   # Bash/Zsh
set archdev (bash /absolute/path/to/tasks-audit/scripts/bootstrap.sh)  # Fish
$archdev = & powershell -NoProfile -File 'C:\path\to\tasks-audit\scripts\bootstrap.ps1'

Then "$archdev" auth status (sign in with "$archdev" auth login if needed; the human finishes the browser step) and read "$archdev" tasks guide.

1. Work out who "me" is

Org Tasks are filtered by assignee with --owner-user <usr_…>, and the CLI has no "me" alias for that flag. Resolve the user's ID once:

  1. If the user gave an ID or a name, use it.
  2. Otherwise read the signed-in email from "$archdev" auth status and match its name part against the assignees on recent Tasks:
    "$archdev" --json tasks list --sort created --order desc --limit 100 \
      | jq -c '[.data[].owner_actor | {id, name, alias}] | unique | .[]'
    owner_actor.id is user-usr_…; the flag takes the usr_… part.
  3. If exactly one assignee plausibly matches, use it and say so on the report's first line ("Auditing Tasks assigned to Calvin Grunewald") so the user can correct it. If none or several match, ask. Never guess.

Personal Tasks (--user me) are a separate collection. Include them only if the user asks, or if the org audit comes back empty. Add --team <id> when the user names a team.

Keep run state outside the checkout, for example ~/.archdev/tasks-audit/<YYYY-MM-DD>/ (mkdir -p first): me.json, inventory.json, one findings-<epic-slug>.json per subagent, and actions.jsonl (one line per change made). It holds no secrets. It is how you resume after a context reset without re-investigating.

2. Inventory

Collect everything assigned to the user that is not moving. Do this in the main session; it is a handful of list calls. Page any full page with --after-cursor (100 is the page maximum).

"$archdev" --json tasks list --owner-user "$me" --status paused --limit 100
"$archdev" --json tasks list --owner-user "$me" --status failed --limit 100
"$archdev" --json tasks blocked            # org-wide, no owner flag: see below
"$archdev" --json tasks list --owner-user "$me" --status in_progress --limit 100   # keep is_stalled == true
"$archdev" --json tasks list --owner-user "$me" --status in_review --limit 100     # keep is_stalled == true
"$archdev" --json tasks inbox              # org-wide, unpaged; join on taskId

tasks blocked covers the whole org and includes open, paused and cancelled rows. Keep .owner_user == $me and drop cancelled; its paused and in-progress rows overlap the lists above, so dedupe by id. Only is_blocked == true means a Task is waiting on unfinished work. blocked_by_count counts every blocker, including done ones, so it is not a blocked signal on its own.

Every paused Task's reason, when one was recorded, is on the Task itself: metadata.pause (kind, category, blocker, question, recommended, rationale, paused_at, paused_by) and metadata.factory_attention (kind, summary, at). Read it straight from the list rows. Many paused Tasks have no inbox row (for example kind: dependency_not_promoted, a pause until a prerequisite ships or a date passes), so the inbox alone undercounts the reasons.

tasks inbox lists paused Tasks waiting on a human, across the org. Join its rows onto the user's Tasks by taskId; its kind, category, question, blocker, recommended, rationale, pausedAt and version match metadata.pause and add the version (the Task's aggregate_version). Keep it: answers pass it as --expected-version.

Sort each Task into one first-pass bucket. Investigation may move it.

BucketSignal
Needs your answerpause kind is needs_decision
Needs access you holdpause kind is needs_access
Waiting for something to ship or a datepause kind is dependency_not_promoted
Human-only steptag human, or inbox kind is legacy_human_task
Waits for a deploytag post_deploy
Waiting on other Tasksis_blocked and none of the above
Failedstatus failed
Stuck mid-workis_stalled (in progress, no activity since stalled_since; often no lease at all)
Paused, no recorded reasonpaused, no metadata.pause, no inbox row, no tag above

A human-only or post-deploy Task that is also blocked belongs to the blocked bucket until its blockers are done: it is not actionable yet. Say so rather than asking the user to do it early.

Write inventory.json and tell the user the counts per bucket in one line before investigating, so they can narrow the audit ("only the Gemini epic", "skip post-deploy").

3. Investigate with subagents

Group the inventory by epic (Tasks without one form their own group). Give each group to one read-only subagent; split a group above about 10 Tasks. Run them in parallel. Each subagent gets a self-contained brief: it has not seen this conversation.

Subagent brief

Pass the archdev path, the user's ID, the group's Task rows from inventory.json (including any inbox row), and this text:

You are auditing paused, blocked and failed ArchDev Tasks for one epic. Read only: do not run tasks update, answer, comment, claim, close, reopen, deps add/remove, or anything that writes. For each Task:

  1. "$archdev" --json tasks show <id> — description, acceptance, current_lease, tags, links.
  2. "$archdev" --json tasks comments <id> --all — pause and block reasons live here. Factory comments are prefixed: [factory:pause kind=…], [factory:needs-operator kind=…], [factory:decision], [factory:implementation_plan], [human:answer]. The newest pause comment and anything after it matter most.
  3. "$archdev" --json tasks deps list <id> — each blocker with its status. Follow blockers that are themselves blocked until you reach the root blocker(s) that are actually stuck, and name them.
  4. For each linked pull request, its state (gh pr view <url> --json state,mergedAt,statusCheckRollup if gh is available).
  5. If a blocker is done, check it shipped: its PR merged, or its commit is on the default branch. A done-but-never-shipped blocker is a finding.
  6. Factory ownership: recent [factory:…] comments, a metadata.factory_attention entry, or a current_lease.session_name starting with factory: mean a Factory is driving it. A stalled Task often has no lease, so don't rely on the lease alone.

Return JSON only, one object per Task, matching the schema below. Quote evidence (comment timestamp and first line, blocker title and status); do not paraphrase it into certainty. If nothing records why the Task stopped, say "reason_known": false.

Findings schema

{
  "task_id": "tsk_…",
  "title": "…",
  "epic": "…",
  "bucket": "needs_answer | needs_access | human_step | waits_for_deploy | blocked | failed | stuck | no_reason | stale",
  "reason_known": true,
  "waiting_for": "one plain sentence: what has to happen next, and by whom",
  "why": "one or two plain sentences on how it got here",
  "evidence": ["2026-10-29 19:25 [factory:pause kind=needs_access] The retained checkout predates …"],
  "root_blockers": [{"task_id": "tsk_…", "title": "…", "status": "paused", "why_stuck": "…"}],
  "factory_owned": false,
  "inbox_version": 24,
  "recommended": "the inbox recommendation, or the subagent's proposed next step marked as a proposal",
  "proposed_actions": ["accept_recommended | answer | access_granted | evidence | rescope_local | add_dep | split_human | cancel | reopen_blocker | ask_overseer | none"],
  "question_for_user": "the one question that unblocks it, or null"
}

stale means duplicate, superseded, or already delivered (the acceptance is met on the default branch): it should probably be cancelled or closed.

Running it

  • Claude Code with the Workflow tool: invoking this skill is the user's request to run the investigation as a workflow. Load the workflow-authoring skill first, then run one agent() per epic group inside parallel(), each with the brief above and the findings schema, and return the merged findings. Keep it to one phase; the main session writes the report. Without the Workflow tool, launch one Agent per group in a single message so they run concurrently.
  • Other harnesses: use their subagent or parallel-task facility with the same brief. With no subagents, investigate the groups yourself one at a time and write each group's findings file before the next.
  • A cheaper or faster model is fine for subagents: the work is reading and summarising, not judgement calls.
  • Check what comes back. Spot-check one finding per group against the Task's comments yourself; send a group back if its evidence does not support its waiting_for.

Save each group's result as findings-<epic-slug>.json.

4. Say it in plain language

The user should understand every line without knowing Factory or Tasks internals. For each Task:

  • Lead with what it is waiting for and who acts. "Waiting on you to approve four live Slack steps", not "paused (needs_decision / live_infrastructure)".
  • Name things by title, not ID. IDs go in a trailing link or column.
  • Relative times. "paused 10 days ago", "stuck since yesterday".
  • Translate internal terms (table below). Keep the raw kind only in the detail view.
  • One sentence of why, then the recommended next step if there is one. Long evidence stays in the detail view.
  • Say when nothing is known. "No reason recorded. The last comment is from the worker on Oct 12 and says tests passed." is better than a guess.
InternalSay
needs_decisionWaiting on your decision
needs_access / credentialsNeeds a credential or secret only a person can provide
needs_access / host_environmentThe worker's machine or checkout needs fixing before it can continue (stale branch, missing tool, workspace setup failed)
needs_access / live_infrastructureNeeds your OK to change a live system
legacy_human_task, tag humanA step only a person can do; once done, mark it done
tag post_deployCan only be checked after a deploy, by watching production
dependency_not_promotedPaused until a prerequisite ships or a date passes (say which, from blocker)
is_blockedWaiting on N unfinished Tasks (name the root one)
failedThe worker gave up: <last error, in a sentence>
is_stalledMarked in progress, but nothing has happened since <time>
rescope_localDrop the part that needs production and close on local proof
access_grantedYou've granted the access; let the worker retry
lease"who's working on it"

5. The report

Order groups by what the user can do right now, quickest first:

  1. Answer and go — has a question and a recommended answer.
  2. Needs you outside ArchDev — access, credentials, live-system approval, human-only steps whose blockers are done.
  3. Broken or stuck — failed, stalled, churn, no recorded reason.
  4. Probably stale — duplicates, superseded, already delivered.
  5. Waiting on other Tasks — grouped by root blocker, so clearing one root shows how much it frees.
  6. Waiting for a deploy — nothing to do until it ships.

Open with one line of totals per group, then the groups as numbered lists:

Auditing 36 Tasks assigned to Calvin Grunewald — 6 need you now.

1. Answer and go (2)
   1.1 Clients receive org task changes over SSE instead of polling
       Waiting on: your OK to move the worker's old checkout onto main.
       Why: the checkout predates code it depends on; its retry work is saved.
       Suggested: approve the supported recovery. · paused today · tsk_0zCP…

For blocked work, draw the chain to the root blocker:

Cloud factory enabled for first org   (waits for deploy)
  └─ Live staging proof: nodes claim a task and open a PR   (needs you: staging creds)
       └─ 12 more Tasks wait on this one

When the audit has more than about 15 Tasks, also offer the report as a page (an HTML artifact, if the harness can publish one): one card per Task with the plain-language lines up front, evidence and IDs folded away, and the groups as sections. The terminal report stays the source of what to act on.

6. Walk through it with the user

Go group by group, in report order. For each Task (or a batch of same-shaped Tasks) offer concrete choices and wait. Use the harness's question tool if it has one; otherwise a numbered list.

  • Accept the recommended answer
  • Answer differently (type it)
  • I've granted the access / here's the evidence
  • Drop the production part and close on local proof (rescope_local)
  • Split the human step into its own Task
  • Cancel it (duplicate / no longer needed)
  • Skip for now

One "yes" covers only the Task it was asked about, unless the user says it covers a batch ("accept all the recommended ones in group 1"). Before an answer, check for earlier direction in the comments: answering without knowing a prior answer was reverted repeats the mistake.

7. Act (approved changes only)

Run each change, then append it to actions.jsonl with the Task, the command, and the result.

DecisionCommand
Accept recommendedtasks answer <id> --accept-recommended --expected-version <v>
Custom answertasks answer <id> "<answer>" --expected-version <v>
Access grantedtasks answer <id> "<what was granted>" --outcome access_granted --expected-version <v>
Evidence suppliedtasks answer <id> "<note>" --outcome evidence --evidence <link> --expected-version <v>
Close on local prooftasks answer <id> "<why>" --outcome rescope_local --drop-acceptance "<exact item>" --expected-version <v>
Human step doneConfirm its blockers are done (deps list), then tasks answer <id> "<what was done>". This marks it done at once, so only after the user says the step really happened
Missing dependencytasks deps add <id> --blocked-by <prereq>
Split a human steptasks create "<step>" --tag human --epic "<epic>" --project <prj>, then straight away tasks update <new> --status paused (create has no status flag; until the update lands the Task is open, and the human tag is the only thing keeping workers off it), tasks deps add <new> --blocked-by <implementation> and tasks deps add <rollout-or-epic-close> --blocked-by <new>
Done blocker never shippedtasks reopen <blocker> (dependents re-block)
Canceltasks comment <id> "<why, and the replacement Task>", then tasks update <id> --status cancelled (check tasks update --help lists the status first; if the update is refused, report it rather than trying another route)
Factory-owned, not answerablecomment the fix, then ask the overseer or its human to resume; do not flip status
  • tasks answer records the answer, comments [human:answer] and reopens the Task for the next worker. --expected-version refuses if the Task changed since the inbox read; re-read the inbox row and re-ask the user instead of retrying with a newer version.
  • --standing applies the answer to matching future pauses. Use it only when the user asks for a standing rule.
  • --tag replaces the whole tag set: re-pass the existing tags (including archdev-plan, plan:<id>, plan-key:<key>) when adding one.
  • Pass long text from a file (--description "$(cat file.md)").
  • Every status change gets a comment saying why and what it unblocks.
  • Approval to answer a Task is not approval to touch live infrastructure. If an answer approves live-system steps, the user's answer is the approval for those steps only as worded.

8. Finish

Re-run the inventory list calls and report:

  1. Changed: each Task, the action, and what it unblocked (newly ready dependents from tasks ready --epic "<epic>").
  2. Still needs you: the open questions, by Task title.
  3. Skipped: Tasks the user passed on.
  4. Not actionable yet: blocked or post-deploy work, with its root blocker.
  5. Couldn't explain: Tasks with no recorded reason, and who to ask.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.