# Self-improvement example

> Recipe: three done tasks with outcomes → reflect writes learning + pending skill-proposal → user accepts → skill file diff and proposal Outcome recorded.

- Repository: superdesigndev/loopany
- GitHub: https://github.com/superdesigndev/loopany
- Human docs: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8
- Complete Markdown: https://grok-wiki.com/public/docs/superdesigndev-loopany-97bd9ab97ae8/llms-full.txt

## Source Files

- `skills/loopany-reflect/SKILL.md`
- `skills/loopany-core/kinds/task.md`
- `skills/loopany-core/kinds/learning.md`
- `skills/loopany-core/kinds/skill-proposal.md`
- `test/skill-regression.sh`
- `src/commands/artifact-status.ts`

---

---
title: "Self-improvement example"
description: "Recipe: three done tasks with outcomes → reflect writes learning + pending skill-proposal → user accepts → skill file diff and proposal Outcome recorded."
---

The self-improvement loop in loopany is a skill-driven workflow (`loopany-reflect`) over three artifact kinds: `task` (evidence via `## Outcome`), `learning` (belief), and `skill-proposal` (pending skill edit). The CLI enforces status machines and frontmatter schemas; pattern thresholds, body sections, and skill-file edits are governed by kind playbooks and the reflect skill. Agents never patch `SKILL.md` files directly—acceptance goes through a proposal artifact plus git.

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| Workspace | `loopany init` with `$LOOPANY_HOME` set |
| Mission | Active `mission` artifact (resolver bootstrap blocks other work without one) |
| Skills | `loopany-reflect` installed and routable from `loopany-resolver` |
| Evidence | ≥ 3 `task` artifacts in `done` with distinct, comparable `## Outcome` sections |

<Note>
`test/skill-regression.sh` scenario 8 asserts reflect must **not** create a `learning` when fewer than three completed tasks exist. Reflect after every single task is an anti-pattern.
</Note>

## Scenario

Three metric-related tasks closed without a `## Before` baseline. Outcomes report numbers but lack a falsifiable before/after. Reflect should generalize that pattern into a `learning`, then a `skill-proposal` that updates the task kind playbook. A human (or delegated agent) accepts the proposal, applies the skill diff, records `## Outcome` on the proposal, and commits.

```text
$LOOPANY_HOME/
  artifacts/tasks/<task-slug>.md     ×3  (status: done, ## Outcome)
  artifacts/learnings/<lrn-slug>.md     (status: active, evidence: tasks)
  artifacts/skill-proposals/<spr-slug>.md (status: pending → accepted)
  references.jsonl                      (mentions / led-to edges)
  skills/...                            (repo checkout — edit target on accept)
```

## Phase 1 — Close three tasks with outcomes

Create and complete three tasks that share the same failure mode (metric work without baseline). Append `## Outcome` **before** flipping to `done` (kind playbook requirement; the CLI does not block `done` without that section).

<Steps>
<Step title="Create first task">

```bash
loopany artifact create --kind task \
  --slug dashboard-lcp-march \
  --title "Improve dashboard LCP" \
  --status todo \
  --content "$(cat <<'EOF'
## Plan
Ship lazy-loading for the heaviest chart widgets.
EOF
)"
```

</Step>
<Step title="Work, append Outcome, mark done">

```bash
loopany artifact status dashboard-lcp-march running
loopany artifact append dashboard-lcp-march --section Outcome --content "$(cat <<'EOF'
LCP improved from ~4.2s to ~2.8s in staging after lazy-loading charts.
No ## Before snapshot; cannot verify production baseline or control for traffic mix.
EOF
)"
loopany artifact status dashboard-lcp-march done --reason "shipped lazy-load"
```

</Step>
<Step title="Repeat for two more tasks">

Use distinct slugs with the same structural gap (e.g. `api-p99-latency-april`, `checkout-conversion-may`). Each `## Outcome` should state what moved and explicitly note the missing baseline.

</Step>
<Step title="Verify evidence pool">

```bash
loopany artifact list --kind task --status done
```

Expect ≥ 3 items. Confirm each body contains `## Outcome` via `loopany artifact get <slug>`.

</Step>
</Steps>

Terminal task statuses and required body sections are defined in the bundled `task` kind; `artifact status` only validates the status machine (`todo` → `running` → `done`, etc.).

## Phase 2 — Reflect: learning + pending proposal

Trigger reflect when the user asks or when ≥ 3 tasks recently reached `done` (not after every task).

<Steps>
<Step title="Gather and filter evidence">

```bash
loopany artifact list --kind task --status done
loopany artifact list --kind learning --status active
loopany artifact list --kind skill-proposal --status rejected
```

Subtract task slugs already listed in `evidence` on active learnings or non-rejected proposals. Default time window ≈ one week (`createdAt`, newest first).

</Step>
<Step title="Apply pattern threshold">

| Pattern | Threshold |
|---------|-----------|
| Same class of outcome | ≥ 3 tasks |
| Belief refuted | ≥ 2 contradicting outcomes |
| Belief needs caveat | ≥ 2 tasks |
| Dismissed signal recurs | ≥ 3 dismissals over ≥ 2 weeks |

Here: ≥ 3 tasks whose Outcomes lack `## Before` on metric work → valid pattern.

</Step>
<Step title="Write learning artifact">

```bash
loopany artifact create --kind learning \
  --slug metric-outcomes-need-before-2026 \
  --title "Metric task outcomes are unfalsifiable without a ## Before baseline" \
  --evidence "dashboard-lcp-march,api-p99-latency-april,checkout-conversion-may" \
  --mentions "<your-mission-slug>" \
  --check-at 2026-09-01 \
  --content "$(cat <<'EOF'
## Observation
Three recent metric tasks reported deltas without reproducible baselines.

## Evidence
- dashboard-lcp-march — "LCP improved… No ## Before snapshot…"
- api-p99-latency-april — "p99 down 18%… no baseline captured"
- checkout-conversion-may — "conversion +0.4pp… traffic mix uncontrolled"

## Scope
Applies to tasks measuring product metrics (latency, conversion, error rates).
Does not apply to pure refactors or docs-only work.

## Check-at
On 2026-09-01: count done metric tasks; do ≥ 80% include ## Before?
EOF
)"
```

`evidence` must cite ≥ 2 artifact IDs; use `--slug` on learnings because they are cited often.

</Step>
<Step title="Write skill-proposal (optional but typical here)">

Only when the learning implies a concrete skill edit:

```bash
loopany artifact create --kind skill-proposal \
  --slug require-before-on-metric-tasks \
  --title "Require ## Before on metric tasks in task playbook" \
  --target-skill skills/loopany-core/kinds/task.md \
  --change-type modify \
  --evidence "metric-outcomes-need-before-2026" \
  --mentions "metric-outcomes-need-before-2026" \
  --check-at 2026-09-01 \
  --content "$(cat <<'EOF'
## Motivation
Learning [[metric-outcomes-need-before-2026]]: three metric tasks closed without baselines.

## Proposed change
**File:** skills/loopany-core/kinds/task.md
**Intent:** Under `## Playbook` / `### Body`, elevate `## Before` from "strongly recommended" to **required** when the task title or Outcome references a measurable metric (LCP, p99, conversion, error rate).
**Location:** After the Outcome bullet list, add a short gate: "Metric tasks: append ## Before before status done."

## Expected effect
- Short term: agents pause to capture baseline screenshots or query snapshots.
- Long term: reflect can falsify beliefs from outcomes; fewer duplicate learnings.

## Check-at
2026-09-01 — sample 10 done metric tasks; measure ## Before presence rate.
EOF
)"
```

Default status is `pending`. Frontmatter uses camelCase flags on the CLI (`--target-skill`, `--change-type`, `--check-at`).

</Step>
<Step title="Verify evidence chain">

```bash
loopany trace require-before-on-metric-tasks --direction backward
```

Expect backward reachability to the learning and cited tasks (via `mentions` / `evidence` frontmatter and explicit `refs` if added).

</Step>
</Steps>

```mermaid
stateDiagram-v2
  [*] --> todo: task created
  todo --> running: artifact status
  running --> done: Outcome appended
  done --> [*]: evidence for reflect

  [*] --> active: learning created
  active --> superseded: new learning supersedes

  [*] --> pending: skill-proposal created
  pending --> accepted: user accept + Outcome
  pending --> rejected: user reject + Outcome
```

## Phase 3 — Accept proposal and apply skill diff

Acceptance is human-gated (`agent proposes, human accepts`). The reflect skill's **Proposal Apply** mode performs the edit.

<Steps>
<Step title="List pending proposals">

```bash
loopany artifact list --kind skill-proposal --status pending
```

</Step>
<Step title="Read proposal, learning, and target file">

```bash
loopany artifact get require-before-on-metric-tasks
loopany refs require-before-on-metric-tasks --direction out --relation mentions
loopany artifact get metric-outcomes-need-before-2026
```

Read `targetSkill` from proposal frontmatter (e.g. `skills/loopany-core/kinds/task.md` in the repo checkout).

</Step>
<Step title="Apply only the described change">

Edit the target file faithfully—scope is bounded by `## Proposed change`. Do not edit skills outside the proposal contract.

</Step>
<Step title="Record Outcome and flip status">

```bash
loopany artifact append require-before-on-metric-tasks --section Outcome --content "$(cat <<'EOF'
Added metric-task gate under task.md Playbook § Body: ## Before required before done when Outcome cites measurable metrics.
Interpretation: strengthens capture quality; does not auto-enforce at CLI layer.
EOF
)"
loopany artifact status require-before-on-metric-tasks accepted \
  --reason "playbook updated per proposal"
```

`skill-proposal` kind requires `## Outcome` on both `accepted` and `rejected` terminal statuses.

</Step>
<Step title="Git commit target + proposal">

```bash
git add skills/loopany-core/kinds/task.md
git add "$LOOPANY_HOME/artifacts/skill-proposals/require-before-on-metric-tasks.md"
git commit -m "accept skill-proposal: require ## Before on metric tasks"
```

</Step>
</Steps>

```mermaid
sequenceDiagram
  participant User
  participant Reflect as loopany-reflect
  participant CLI as loopany CLI
  participant WS as $LOOPANY_HOME
  participant Git as git

  User->>Reflect: reflect / accept proposal
  Reflect->>CLI: artifact list --kind task --status done
  CLI->>WS: read tasks + Outcomes
  Reflect->>CLI: artifact create --kind learning
  Reflect->>CLI: artifact create --kind skill-proposal
  CLI->>WS: pending proposal
  User->>Reflect: accept require-before-on-metric-tasks
  Reflect->>Reflect: edit targetSkill file
  Reflect->>CLI: artifact append Outcome
  Reflect->>CLI: artifact status accepted
  Reflect->>Git: commit skill + proposal artifact
```

### Reject path (contrast)

```bash
loopany artifact append <proposal-slug> --section Outcome --content "Rejected: change belongs in capture skill, not task kind."
loopany artifact status <proposal-slug> rejected --reason "wrong target"
```

Rejected proposals are listed on the next reflect pass so the same rule is not re-suggested.

## Verification checklist

| Check | Command / signal |
|-------|------------------|
| Three done tasks | `loopany artifact list --kind task --status done` → count ≥ 3 |
| Outcomes present | `loopany artifact get <task-slug>` → body contains `## Outcome` |
| Learning active | `loopany artifact list --kind learning --status active` |
| Proposal terminal | `loopany artifact get require-before-on-metric-tasks` → `status: accepted`, `## Outcome` |
| Skill diff landed | `git log -1 -- skills/loopany-core/kinds/task.md` |
| No duplicate reflect | `evidence` on new learnings excludes already-processed task slugs |

<Warning>
Do not edit `SKILL.md` or kind files without a `skill-proposal` artifact. Direct skill edits bypass the evidence chain and break the "agent proposes, human accepts" constraint from project architecture.
</Warning>

## Status machines (quick reference)

| Kind | Initial | Terminal transitions |
|------|---------|------------------------|
| `task` | `todo` | `done`, `failed` require `## Outcome` (playbook) |
| `learning` | `active` | `superseded`, `archived` require `## Outcome` (playbook) |
| `skill-proposal` | `pending` | `accepted`, `rejected` require `## Outcome` (playbook) |

CLI `artifact status` enforces **legal edges only** (e.g. `pending` → `accepted`). Body section gates are agent discipline unless a future validator adds them.

## Anti-patterns this example avoids

- Reflecting on one task (insufficient pattern).
- Creating a `skill-proposal` without a backing `learning`.
- Re-proposing a `rejected` change without reading `loopany artifact list --kind skill-proposal --status rejected`.
- Accepting without `## Outcome` on the proposal.
- Editing beyond `## Proposed change` scope.

## Automated regression

`test/skill-regression.sh` installs four skills into a temp workspace, seeds a mission, and runs Claude-driven scenarios—including scenario 8 (reflect declines when &lt; 3 tasks). Run from repo root:

```bash
./test/skill-regression.sh        # all scenarios
./test/skill-regression.sh 8      # reflect threshold only
./test/skill-regression.sh --dry-run
```

Requires `claude` CLI and API credentials; see script header for prerequisites.

Unit/E2E CLI tests cover `artifact append` / `status` and lifecycle flows in `test/scenario.e2e.test.ts` (signal → task → `## Outcome` → `done`) but do not automate the full reflect → accept → git path—that remains skill-guided.

## Related pages

<CardGroup>
<Card title="Self-improvement loop" href="/self-improvement-loop">
Concept: Outcome evidence, learnings, proposals, checkAt, and the no-direct-skill-edit rule.
</Card>
<Card title="Reflect workflow" href="/reflect-workflow">
Operational reflect and proposal-apply steps in depth.
</Card>
<Card title="Kinds and validation" href="/kinds-and-validation">
Dynamic schemas, status machines, and immutable write semantics.
</Card>
<Card title="Artifact commands" href="/artifact-commands">
`create`, `append`, `status`, and per-kind `--field` flags used above.
</Card>
<Card title="Build and test" href="/build-and-test">
`bun test`, E2E workspaces, and `skill-regression.sh` requirements.
</Card>
</CardGroup>