Skip to content

rebelytics/one-skill-to-rule-them-all / skills/task-observer

task-observer

Verified

Turns corrections, repeated workflows and judgement calls from work sessions into small, evidenced skill updates: logs each observation with its source, stages every change for your approval, and flags repeating work as new skills. Use during ANY multi-step task, agentic workflow, or work session. Also triggers in post-task feedback discussions and when the user mentions skill observations, the observation log, or skill taxonomy. Also known as "One Skill to Rule Them All" — trigger on this phrase too. IMPORTANT: invoke this skill before the FIRST tool call of any session and before writing or proposing a plan — any turn that will involve a tool call counts. This sentence is the session-start trigger and the only activation layer that survives an unreachable config file; pair it with a CLAUDE.md instruction or a session-start hook (references/environments.md). A subagent dispatched by a session already running it does not run it: it writes nothing and puts its findings in its report.

FileKindSize
LICENSEother18.2 KB
SKILL.mdskill md39.1 KB
references/acting-on-observations.mdmarkdown4.9 KB
references/ceilings.txtmarkdown9.9 KB
references/environments.mdmarkdown134.0 KB
references/migration.mdmarkdown13.2 KB
references/observation-families.mdmarkdown12.1 KB
references/observation-log.mdmarkdown68.7 KB
references/observation-scan.mdmarkdown34.4 KB
references/review-slice.mdmarkdown3.1 KB
references/signals.mdmarkdown13.1 KB
references/skill-authoring.mdmarkdown92.2 KB
references/starter-principles.mdmarkdown31.0 KB
references/weekly-review.mdmarkdown165.2 KB
scripts/bin-check.shexecutablescript5.9 KB
scripts/diff-staged.shexecutablescript5.5 KB
scripts/extend-observation.shexecutablescript11.1 KB
scripts/migrate-log.pyscript25.1 KB
scripts/new-observation.shexecutablescript23.6 KB
scripts/session-start-scan.shexecutablescript56.6 KB
scripts/set-fields.shexecutablescript21.6 KB
scripts/skill-load.shexecutablescript11.0 KB
scripts/stage-patch.shexecutablescript4.4 KB
scripts/validate-skill-bundle.pyscript227.5 KB

references/signals.md

View on GitHub
# Signals — what to watch for, in full

Load triggers: unsure whether something is worth logging or generalises; sorting many candidate observations; deciding in a review what a skill should lose; a defect that is not the deliverable takes a second hypothesis; the same rule broken a second time, before proposing a fix, or why a first violation is logged; before writing any "later" into a recommendation

The core skill carries the short trigger list; this file is the full
catalogue with examples, loaded on the triggers above.

## Contents

- Signals for a NEW skill
- Signals for IMPROVING an existing skill
- Signals for SIMPLIFYING a skill
- The generalisability test
- An unresolved defect is an observation, at a bounded point
- Second violation — why a barrier, not a rewording
- Do NOT log
- Where the observation mindset stays on
- Deferral disguised as diligence
- Instructions handed across a boundary
- A command's risk is what it does, not what it was reached for

## Signals for a NEW skill

A reusable multi-step workflow; a methodology the user explains that no
existing skill captures; a recurring task type with similar structure; a
process with clear inputs, phases, outputs; the user describing a refined
process ("I always do it this way"); a structured approach emerging
naturally during work.

When one fires, the observation's `proposes_skill:` list names the
candidate by a working name. The observation may also list existing skills
under `skill:` if the same insight improves them.

## Signals for IMPROVING an existing skill

Anything from a task that used a skill and could make it better —
problems, positive signals, or neutral gaps. Examples:

- the agent violates a documented rule (the skill needs enforcement, not
  louder rules);
- a user correction reveals a missing rule or edge case;
- a better workflow emerges than the skill recommends;
- a technique works well enough to promote from incidental to recommended;
- an undocumented use case;
- feedback that generalises;
- a wrong assumption;
- the skill states something the session's own evidence — tool output, a
  live page, a file — contradicts: log it even when the user never
  notices; this is the runtime counterpart of the Timelessness rule
  (`skill-authoring.md`), catching the current-state claim that slipped
  through at authoring time;
- new tooling obsoletes a step;
- corrections forming a pattern;
- a principle that applies to other skills too;
- a naming, framing or structural suggestion, even a conversational one.

## Signals for SIMPLIFYING a skill

A section never relevant across many sessions; a rule from a single
unvalidated observation; workflows users consistently shortcut; sections
loaded but never acted on; contradictory rules; "just in case" complexity
that never triggered; a rule the agent consistently fails to follow
(convert it to structural enforcement — a checklist, a verification step,
an unskippable tool call — or remove it). Treat these as a review
checklist; ask "what can we remove?" as deliberately as "what should we
add?"

## The generalisability test

Before recording a candidate improvement, ask: (1) would this correction
still make sense in another project? (2) would it apply to another task
using the same skill? (3) does it identify a missing rule, workflow step or
principle, rather than merely fix this task? (4) is there evidence the
issue is likely to recur? If the answers are mostly no, treat it as
task-specific context rather than an observation. A workaround that only
applies to one repository, a preference specific to one user, a decision
forced by a temporary constraint — these look like skill improvements
while the task is happening and are not. Instead of "the user preferred
modules in a single repository", log "the skill lacks guidance for
deciding when shared modules should be centralised". Knowing when *not*
to learn is as important as detecting signals: over-learning from isolated
examples is how a skill drifts into over-specific complexity.

## An unresolved defect is an observation, at a bounded point

**An unresolved defect is an observation, at a bounded point.** When a
defect that is not itself the deliverable is consuming the session — one
more hypothesis, one more root-cause probe — there is a point at which the
right output is a precise, evidenced problem report, logged as an
observation (or as an issue where the defect belongs to someone else's
code) and the deliverables resumed. Set that point before the second
hypothesis, not after the fifth: a report that names the symptom, what was
ruled out and the cheapest next test is a legitimate deliverable, and it
is what the next session or the upstream maintainer needs; the fix found
in a file the project's own rules protect from unapproved edits was never
going to ship from this session anyway. This skill does not carry
debugging methodology — only the observation-capture rule at the boundary.

## Second violation — why a barrier, not a rewording

A first violation is already an observation: breaking a rule that a skill or a project instruction file documents is
not an embarrassment to move past: it is the only evidence that the rule's
*enforcement* is too weak, and nobody but the agent can see it.

The core carries the rule: from a rule's second failure onward, the proposed
improvement is a structural barrier, not better wording. This is why, and
what counts as a barrier. A rule that has
failed twice with no intervening `actioned` fix has a protection problem, not a
wording problem: never a clearer sentence, a bolder warning,
or the same rule moved somewhere more prominent.

The observed case: one documented rule broken three times in three separate
sessions. The rule lived in a project instruction file re-read at the start
of every session, so it was never "unloaded" — it was in context each time
it broke. Each occurrence was handled correctly by the text as it then
stood, and the first two produced only new wording:

| Occurrence | What was logged | What changed |
|---|---|---|
| 1st | rule broken, add a post-write check | wording |
| 2nd | rule broken *again*, same rule | wording, more emphatic |
| 3rd | "this needs a barrier, not a rule" | a pre-tool hook that refuses the call |

Only the third changed the outcome. The first two were not mistakes in
diligence — they were the natural output of a loop whose only available
lever is text.

**Why text loses.** A rule in context is re-interpreted on every run and
competes with everything else pulling at the same moment; a barrier at the
tool boundary does not compete, it refuses. Emphasis does not change that
asymmetry — an emphatic rule is still a rule, and the third rewrite reads as
diligence while changing nothing measurable.

**What counts as a barrier**, roughly in order of preference: a hook or
permission rule that refuses the call; a lint or gate check that fails the
artefact; a default or path layout that makes the wrong action unavailable;
a script that performs the step so it cannot be performed differently. What
does not count: a bolder warning, the same rule moved somewhere more
prominent, a checklist item, or a promise to be careful.

**A barrier counts once it is armed, not once it is written** — and a
change to an existing one, including a new branch added behind an entry
point that is already registered, is a new barrier for this purpose.
Arm it the way `observation-scan.md` arms any enforcement trigger ("Two
gaps the checkpoint pairing still leaves — and the rule behind both"): the
real command it must refuse, and a legitimate one from the real tool
record, both run through it. Passing synthetic payloads are evidence about
the author's model of the input, not about the input, and the proof of the
other triggers in the same file says nothing about the added one. For a
barrier on shell commands, this skill's own snippets are legitimate
commands it will meet early — the id derivation is a compound script with
command substitution, the session-start scan a bundled script's
invocation — so include them.

**Where this matters most** is the class where the absence of an error is
not evidence of success — silent corruption, a command that exits 0 having
done the wrong thing, a check that cannot come out negative. There, a
missed rule produces no signal at all, so the loop that would eventually
catch a wording failure never starts.

## Do NOT log

One-off corrections that don't generalise; preferences already captured in
a skill; tool bugs unrelated to methodology; observations that would need
proprietary client information to be useful in an open-source skill
(unless an internal skill is the right home).

## Where the observation mindset stays on

Active for the entire task session: execution, post-task feedback and
review discussion, meta-discussion about skills or methodology, and
reflective or strategy conversations about how work should be done. The
observation mindset does not deactivate when the conversation shifts from
doing the work to discussing it — user feedback in review phases is often
the highest-signal input. Inactive only for casual conversation and quick
factual questions with no tools or deliverables involved.

## Deferral disguised as diligence

**Deferral wears a second disguise: not a promise, but an argument.** "Let's
wait until this has seen a few days of real use", "we should gather more data
first" — this reads as diligence, which is exactly why it goes unchallenged,
including by the person saying it. It is not an announcement, so a rule about
executing rather than announcing does not catch it. So before writing *any*
"later" into a recommendation, name two things: **which specific observation
would change the decision, and when it could realistically arrive.** If you
cannot name one, the evidence is either already conclusive (act now) or waiting
adds nothing (act now). A criterion you *can* name must also be able to occur:
ask who or what would have to act for it to fire, and whether that party has a
reason to do exactly the opposite — a deferral whose criterion cannot occur is
indistinguishable from a silent drop, only more expensive, and it looks better
than a vague one because it is precisely phrased. Probe the action as well
as the evidence: when deferring, check read-only that the deferred action
can be taken at all (the feature exists, the plan includes it, the
permission is there) and record the result; a failed probe means deciding
now and naming the substitute. Then ask what the delay
costs — if a known-defective
state stays live meanwhile, the burden of proof is on deferring, not on acting.
A deferral is a decision and needs the same justification as acting; "more
evidence would be better" is not one, because the question is whether more
evidence could change the OUTCOME.

## Instructions handed across a boundary

A command block, a procedure or a checklist handed to a human is executed
in an environment the author has not tested: the author's shell, flags and
assumptions do not travel with the text. Anything optional in that text — a
trailing comment, a line break between two steps that only make sense
together, an implied ordering — is a place where the receiving environment
gets to decide, and it decides differently from the author at least once.
(Observed: a `# comment` trailing a command in a paste-able block was passed
to the tool as arguments by an interactive shell that has comments off by
default; the step silently failed and the next line acted on a state that
had never arrived.) So: explanation goes in the prose around a block, never
on a command line; steps whose order matters are chained so a failure stops
the sequence; and the check that settles whether the step worked tests the
PROPERTY the step exists for, not the command's exit. A handover whose
failure was detected by the recipient reading output is an observation, and
its second occurrence is a barrier (above), not a rewording.
A path is the commonest such instruction: one that resolves inside the
agent's execution context can point at nothing from the user's shell,
packaging or synced folders (`environments.md`, "Paths handed across a
boundary are resolved from the far side").

## A command's risk is what it does, not what it was reached for

Classify a command by its EFFECT before running it — does it write, and
where? — never by the intent it was reached for. A verb chosen for its read
half performs its write half regardless, in whatever repository, branch,
index or account it is pointed at, and the blast radius is set by the
target, not by the intent. (Observed: a version-control "checkout <ref> --
<path>" run to copy files OUT of a branch wrote that branch's whole tree
into the current branch's index; the next routine commit-and-push
published untested content on a public default branch, and every content
gate passed because none of them looks at what is staged in a different
repository.) The tell is a convenience shortcut taken in a location the
process reserves for something else — a read-only clone, a production
branch, a shared log — "just this once". Log it when caught; the fix is a
rule stated as a property of the LOCATION ("this repository is read-and-push
only"), because a rule stated as a property of the task does not feel like
it covers the task that was not the task.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall