diff --git a/skills/active-listening/SKILL.md b/skills/active-listening/SKILL.md new file mode 100644 index 0000000..c7b2c9d --- /dev/null +++ b/skills/active-listening/SKILL.md @@ -0,0 +1,38 @@ +--- +name: active-listening +description: > + Gather every requirement before acting. Trigger at the start of any task + whose scope, constraints, or success criteria are not fully pinned down, and + whenever another skill needs an operator-only fact — ask focused questions + until nothing needed is still open, then reflect the understanding back. + Portable across projects. +--- + +Do not act on a half-understood request. Listen actively until you could state +the task, its constraints, and its definition of done without guessing. + +## Procedure + +1. **Surface the unknowns.** List every open question the task leaves: ambiguous + scope, unstated constraints, success criteria, edge cases, which files or + systems are in play, what "done" means, and any decision only the operator + can make. +2. **Derive what you can first.** Remove from that list every question you can + answer yourself from the code, the logs, the git history, or a sensible + default. Active listening is not offloading your own investigation onto the + operator. +3. **Ask, focused.** Put the genuinely-open questions to the operator — grouped, + concrete, answerable, with a recommended default where one exists. Prefer a + few high-leverage questions over a long interrogation. Use the host's + structured question mechanism when one exists. +4. **Listen and integrate.** Fold each answer in. A new answer often opens a new + question — keep going. +5. **Loop until closed.** Repeat until no needed information is still open. +6. **Reflect back.** Restate the task, its constraints, and its definition of + done in your own words for a final confirmation before acting. + +## Rules + +- Never invent an answer to an open question to avoid asking. +- Never ask what you can determine yourself. +- One genuinely-blocking unknown is enough reason to ask; do not proceed past it. diff --git a/skills/dialectic/SKILL.md b/skills/dialectic/SKILL.md new file mode 100644 index 0000000..42607b0 --- /dev/null +++ b/skills/dialectic/SKILL.md @@ -0,0 +1,52 @@ +--- +name: dialectic +description: > + Reach a defensible conclusion through a dialectical process — thesis, + adversarial antithesis, synthesis — iterated until one thesis survives every + attack at ~99% confidence. Trigger for any consequential root-cause, design, + or decision where being wrong is expensive and the answer is not yet certain. + Deep-inspects every accessible source. Portable across projects. +--- + +Reach the truth by dialectic, not by first guess. Do not stop at a plausible +answer; drive the loop until a thesis survives every attack at ~99% confidence. + +## Before you start: listen + +Invoke the `active-listening` skill first. Do not begin the dialectic until you +have gathered every requirement, constraint, and success criterion the task +needs. A dialectic run on the wrong question wastes the whole loop. Return to +`active-listening` mid-loop whenever an objection turns on a fact only the +operator holds. + +## The loop + +1. **Thesis.** Form the strongest initial claim you can, grounded in evidence, + not assumption. Deep-inspect every source you can reach: the source code and + git history; the running containers (exec, logs, inspect through whatever + make or CLI helpers the project exposes); CI logs and artifacts; tests; docs. + Cite `file:line` and command output — never a bare assertion. +2. **Antithesis.** Spawn MULTIPLE independent skeptics (parallel subagents or a + workflow) whose only job is to REFUTE the thesis. Each re-inspects the + sources itself and defaults to "refuted" on any concrete hole. Give diverse + skeptics diverse lenses: correctness, an alternate mechanism, does-it- + reproduce, does-the-fix-break-something-else. +3. **Synthesis.** Fold every surviving objection back into a refined thesis. A + skeptic that found a real hole replaces or corrects the thesis; a skeptic + that failed to refute raises confidence. +4. **Iterate.** Repeat thesis → antithesis → synthesis until a full skeptic + round finds no new hole and the thesis holds at ~99%. If confidence stalls + below 99%, name the exact residual and the evidence that would close it, then + go get that evidence (more inspection, or `active-listening` for an + operator-only fact) and loop again. + +## Rules + +- Executed evidence beats reasoning: run it, exec into it, read the log. A + thesis backed only by static reasoning caps in the low nineties. +- The antithesis MUST be independent — never let the thesis-author be its own + sole skeptic. +- Diversity over redundancy: skeptics with different lenses catch failure modes + identical skeptics miss. +- Report the final thesis with its evidence AND the losing objections, so the + operator sees why it survived. diff --git a/skills/robot/SKILL.md b/skills/robot/SKILL.md new file mode 100644 index 0000000..2488c5a --- /dev/null +++ b/skills/robot/SKILL.md @@ -0,0 +1,38 @@ +--- +name: robot +description: > + Work fully autonomously to a goal. Trigger when the operator wants hands-off, + uninterrupted execution — the agent drives the task to completion without + check-ins, never stops before the goal is reached, and uses only commands it + is already cleared to run. Portable across projects. +--- + +Operate as an autonomous robot: given a goal, reach it without hand-holding. + +## Contract + +- **No questions once the goal is clear.** Clarify only genuinely-blocking + unknowns up front (via the `active-listening` skill), then proceed without + further check-ins. Pick the cleanest option and continue; never pause to + confirm a choice you can make yourself. +- **Never stop before the goal.** Do not end the run, hand back, or declare done + while any part of the goal is unmet — premature termination is forbidden. A + blocker is something to solve or route around, not a reason to quit; if one + step is genuinely, externally impossible, surface exactly why and keep working + on everything else until nothing solvable remains. +- **Stay inside your clearance.** Use ONLY commands you are pre-authorized to + run. Never invoke anything the agent or tool settings mark as denied or as + requiring per-invocation approval (ask) — no commit, push, deploy, or other + approval-gated action unless the operator has already cleared it for this run. + When a needed action is out of clearance, do all the cleared work and report + the single blocked step for the operator to run. +- **Verify, do not assume.** Reaching the goal means proving it: run it, read the + output, confirm the end state. Never report success on a step you did not + actually verify. + +## Rules + +- Escalate an uncertain root cause or design decision to the `dialectic` skill + rather than guessing; uncertainty is never a reason to stop. +- Sustain the loop across long, multi-step work — the run is finished only when + the whole goal is verifiably met. diff --git a/skills/triage/SKILL.md b/skills/triage/SKILL.md new file mode 100644 index 0000000..4e03d1b --- /dev/null +++ b/skills/triage/SKILL.md @@ -0,0 +1,44 @@ +--- +name: triage +description: > + Triage a failing CI run, pipeline, or job set to a verified root cause and a + real fix. Trigger when a build, test, or deploy pipeline has one or more failed + jobs. Applies the dialectic skill to every failing job independently. Portable + across projects. +--- + +Drive a red pipeline to green by root cause, not by guesswork. Treat every +failing job as its own investigation, and do not declare a fix until that job's +root cause is proven. + +## Procedure + +1. **Enumerate every failing job.** Pull the run's job list and isolate each job + whose conclusion is failure, cancelled, or timed-out. A downstream aggregate + job that fails only because an upstream job did is not a separate root cause — + note it and move on. +2. **Dialectic per failing job.** For EACH failing job, invoke the `dialectic` + skill: form a thesis about the root cause from evidence (the job log, its + artifacts, the code at the run's commit, git history), attack it with + independent skeptics, and iterate to a ~99% thesis. The jobs are independent, + so run their investigations in parallel where the tooling allows. +3. **Distinguish shared vs hidden causes.** When several jobs share one root + cause, fix it once. When a job hides a second failure behind the first, keep + going until the job is actually green, not just past the first error. +4. **Fix at the root.** Apply the real fix in the repository for each proven root + cause. Never mask a failure — no retry-until-pass, no disabling the check, no + soft-skip. If a failure is genuinely external (upstream outage, flaky infra), + confirm that with evidence and surface it honestly instead of fixing around + it. +5. **Follow the run.** While the run is still in progress, re-check it + periodically and triage each newly failed job as it appears. The run is done + only when it has finished and every failure has a verified fix. + +## Rules + +- Executed evidence beats reasoning: read the actual failing log line and the + artifact, not the job title. +- Classify each failure: a real defect (fix it), a flake or infra hiccup (prove + it is transient before dismissing), or already-fixed-by-a-later-commit (verify + the fix is present in the run's commit before claiming it). +- Report a per-job verdict: root cause, the evidence that proves it, and the fix.