Skip to content

azusachino/harus-skills / skills/revise

revise

Verified

Persist project lessons, findings, and wrong approaches so future work can recall them

Revise

Persist durable lessons from the current work into the owning repository's stated lesson home, or into the asobi graph when the repository names none. The Asobi skill's task notes record where the work is; this records what should change future behaviour.

When to use

After a meaningful discovery — a workflow worth repeating, a non-obvious project fact, or (most importantly) a dead end an agent should not re-walk. Capture while context is fresh. Not for ordinary task status, which belongs in the task's sync notes.

Classify

Read the user's free-form text and classify it yourself; ask only if it is too vague to preserve. Keep each lesson short and actionable — "do X because Y", not a transcript.

ClassMeansDestination
work-experiencehow work was actually done[project] observation
findinga non-obvious fact or gotcha (an architectural choice → a decision entity, per the Asobi skill)[project] observation
wrong-approachsomething tried and rejected[project]:pitfall:<slug> entity

Flow

Before any graph step, check the owning repository's instructions (AGENTS.md, CLAUDE.md) for a named home for lessons or pitfalls; harus-workstation, for example, names docs/runbooks/pitfalls/. If one is named, dedup against it, write the lesson there under that repository's own conventions and templates, confirm, and skip the graph. The steps below apply only when none is named.

  1. Detect asobi: command -v asobi. If absent, use the fallback files below.

  2. Derive [project] from the owning repository and confirm graph scope using the Asobi skill's discovery rules. Ancestor configuration can select a parent workspace graph. Use the intended graph; do not initialize or migrate state as a side effect of lesson capture.

  3. Dedup first: asobi search "<topic>" --limit 10. Inspect matching entities. Append seen-again YYYY-MM-DD: <evidence> only for genuinely new evidence; skip an unchanged repeat. If the lesson contradicts an old one, record the correction and resolve the obsolete pitfall rather than reinforcing it.

  4. Write — ensure the project entity exists (asobi new "[project]" "project"), then:

    asobi obs "[project]" "experience YYYY-MM-DD: <lesson>"   # work-experience
    asobi obs "[project]" "finding YYYY-MM-DD: <lesson>"      # finding
    

    For a wrong-approach, write the pitfall entity below.

  5. Confirm in one line.

Pitfall entity

A pitfall warns future agents away from a rejected path — it is not an ADR (ADRs explain chosen paths). One entity per dead end; status and title are truths, so the start-of-work read can surface active pitfalls with a lean search --where status=active rather than opening every entity.

asobi new "[project]:pitfall:<slug>" "concept"
asobi truth "[project]:pitfall:<slug>" status active        # active | resolved
asobi truth "[project]:pitfall:<slug>" title "<short warning>"
asobi obs "[project]:pitfall:<slug>" "tried: <approach attempted>"
asobi obs "[project]:pitfall:<slug>" "why-it-failed: <root cause / symptom>"
asobi obs "[project]:pitfall:<slug>" "do-instead: <better path, or 'open'>"
asobi obs "[project]:pitfall:<slug>" "date: YYYY-MM-DD"

When the dead end is obsolete: upsert status resolved and append obs "resolved YYYY-MM-DD: <why it no longer applies>". If it belongs to an active task, link it with asobi link "[project]:[epic]:task-N" "[project]:pitfall:<slug>" "depends_on". The agent must read those relations and the relevant lesson before dispatch; claiming a task does not load the warning automatically. Slugs are lowercase, - inside a segment and : only between levels — e.g. harus-skills:pitfall:bump-tool-overreach.

Recall

Revise captures lessons; the Asobi skill handles start-of-work recall and the agent's pre-dispatch lesson search. Prefer pitfall titles that state a concrete warning. Preserve evidence and its limits: an observed failure is not proof of a root cause, and one task's workaround is not a universal policy.

Fallback (asobi unavailable)

A lesson-capture fallback; it does not provide graph-backed task continuity. Use the repository's existing lesson or pitfall convention first. If none exists, append to these repo-tracked files with the header > Project-local fallback lessons captured when asobi was unavailable. Migrate into asobi when possible.

  • docs/lessons/pitfalls.md — ## YYYY-MM-DD — <slug>, then Status / Tried / Why it failed / Do instead
  • docs/lessons/learnings.md — ## YYYY-MM-DD — <title>, then Type (work-experience|finding) / Lesson

Confirmation

After a write, confirm its destination. For an unchanged repeat, say No revision needed: existing lesson already covers this evidence. Do not claim a save when nothing was written.

Revision saved: <class> -> <destination>.            # or: -> docs/lessons/<file>.md (asobi unavailable)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall