Skill: leostehlik/better-every-run (version 0.2.1)

--- name: ber description: "Better Every Run: turn explicit /ber corrections into preferred future outcomes through a small fix, remember, and report flow." user-invocable: true metadata: version: "0.2.1" --- # Better Every Run Use this skill only when the user explicitly invokes `/ber`, names Better Every Run, or directly asks to persist a lesson for future runs. Do not auto-capture ordinary corrections, casual preferences, or words like "remember", "always", "never", or "next time" unless the user clearly wants durable learning. The human path is deliberately small: ```text /ber fix bad outcome -> desired outcome /ber remember simple rule /ber report ``` The agent runs the bundled local helper and reports the result in chat, including whether anything was written locally or appended to a durable memory file. ## When To Use - The user explicitly types `/ber fix ... -> ...`. - The user explicitly types `/ber remember ...`. - The user explicitly asks for a Better Every Run report. - The user asks the agent to record a reusable correction as durable memory. ## Human Commands ```text /ber fix agent wrote vague status -> agent gives exact command output and next action /ber remember use the approved development host for active code work /ber report ``` ## Rules - Report CLI output back in chat; do not build web pages or dashboards. - Do not silently edit `MEMORY.md`, `AGENTS.md`, `SOUL.md`, or other durable instruction files. - Only append to a durable memory file when the user explicitly asked for persistence or approved the target. - Keep corrections factual: bad outcome, desired outcome, target file if applying. - Avoid private data unless the user explicitly wants it captured. - Keep the user-facing flow short, but disclose persistence: local store, durable target file if used, and how to review it. - Design for the shortest path to the user's outcome. - Never publish `.better-every-run/` state, local lessons, event logs, or private corrections. ## Workflow For normal chat use, keep the visible flow to one command: ```text /ber fix bad outcome -> desired outcome ``` For simple one-line preferences: ```text /ber remember simple rule ``` Use `/ber report` to show what was learned. ## Agent Implementation Keep low-level helper commands out of normal chat unless debugging, but never hide persistence. A normal answer should say whether the lesson was recorded only in `.better-every-run/` or appended to a named durable file. Read `references/workflow.md` for the full workflow. Read `references/report-template.md` for expected chat output shape. Before publishing or packaging, verify: - `.better-every-run/` is excluded - `make test` passes - examples contain no private workspace paths, chat IDs, tokens, or hostnames - docs say activation is explicit-only and persistence is disclosed

path: LICENSE
content: MIT License

Copyright (c) 2026 Leo Stehlik

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


path: Makefile
content: .PHONY: test

test:
	bash tests/smoke.sh


path: README.md
content: # Better Every Run

Lightweight run learning for OpenClaw agents.

Better Every Run turns explicit `/ber` corrections into future behavior. It does not auto-capture casual chat. The user gives a short command, and the agent reports what was recorded and where it was stored.

## Human Surface

In OpenClaw chat:

```text
/ber fix vague status update -> exact command output and next action
/ber remember design software for humans from the shortest path to outcome
/ber report
```

The agent handles the local helper, then tells the human whether the lesson stayed in the project-local `.better-every-run/` store or was appended to a named durable memory file.

## Product Rule

- The skill runs only from explicit `/ber` use or a direct request to persist a lesson.
- Humans should not manage accept/export/apply steps during normal use.
- The agent should summarize the outcome in chat, including the storage location.
- Durable memory writes must be explicit and target a real file.
- No plugin, server, web UI, database, or external service is required.

## Storage

The helper writes a project-local evidence trail under `.better-every-run/`. That folder should stay private, be excluded from publishing, and can be reviewed or deleted by the workspace owner.

## Internal Helper

The bundled helper is for agents, tests, and audits. Keep normal chat short, but disclose persistence and durable target files clearly.

## Verify

```bash
make test
```


path: examples/demo.md
content: # Demo

From any project directory:

```text
/ber fix agent gave a vague update -> agent gives exact command output and next action
/ber remember design human-facing software around the shortest path to outcome
/ber report
```

Expected result: the OpenClaw agent responds with the captured lesson or report and says where it was stored. Local evidence stays under `.better-every-run/`; durable memory files are changed only when explicitly targeted.


path: references/report-template.md
content: # Report Template

Use this shape when summarizing Better Every Run output in chat:

```text
Better Every Run report:

- Events captured: N
- Lessons accepted: M
- Open proposals: K
- Local store: `.better-every-run/`
- Durable files changed: none or `<path>`

Captured lessons:
1. ...
2. ...

No open proposals. Nothing waiting for manual accept/export/apply. No durable memory file was changed unless listed above.
```

Keep the user-facing report short. Mention internal commands only when debugging or auditing.


path: references/workflow.md
content: # Better Every Run Workflow

Better Every Run is for small, factual learning moments that the user explicitly wants persisted.

OpenClaw command name: `ber`.

## Normal Human Path

Use one command for outcome corrections:

```text
/ber fix agent used wrong host for code work -> agent uses the approved development host
```

In OpenClaw chat, the human-facing prompt should be this simple:

```text
/ber fix agent used wrong host for code work -> agent uses the approved development host
```

The agent handles the helper command and reports the result, including whether data was written only to `.better-every-run/` or also to a durable memory file.

For simple preferences:

```text
/ber remember do GitHub/code work on the approved development host, not in the agent workspace
```

## Internal Capture

Capture only evidence that would change future behavior and was explicitly requested through `/ber` or direct durable-learning instruction:

```bash
node scripts/ber.js capture --type correction --note "Do GitHub/code work on the approved development host, not in the agent workspace." --tags workspace,coding
```

Good captures:

- User explicitly asks `/ber fix ... -> ...`.
- User explicitly asks `/ber remember ...`.
- User directly asks to record a reusable workflow or safety boundary.
- A tool recovery path is reusable and the user approves capturing it.

Bad captures:

- Generic advice the base agent already knows.
- Private details unrelated to future behavior.
- Speculation without observed evidence.
- Casual chat containing words like "remember", "always", "never", or "next time" without clear durable-learning intent.

## Propose

Turn recent evidence into lesson proposals:

```bash
node scripts/ber.js propose --today
```

Proposals are not policy. They are review candidates.

## Report

Return the report in chat:

```text
/ber report
```

Keep the chat report short. Include storage status and any open proposed lessons.

## Apply Durable Memory

This flow is for audits, tests, and explicit durable writes. In normal chat, summarize the result instead of making the human operate the helper commands, but disclose any durable target file.

```bash
node scripts/ber.js accept <lesson-id>
node scripts/ber.js export-memory-patch
node scripts/ber.js apply-memory-patch --target memory/decisions.md
```

Use `export-memory-patch` in chat before applying when a durable file write is risky or ambiguous. Normal `/ber fix` and `/ber remember` use should stay concise, while clearly saying where the lesson was stored.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)