# Reflect workflow

> Gather recent outcomes and dismissed signals, pattern thresholds, write learning and skill-proposal artifacts, and accept/reject proposals with git-backed skill diffs.

- 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/learning.md`
- `skills/loopany-core/kinds/skill-proposal.md`
- `src/commands/artifact-list.ts`
- `src/commands/artifact-status.ts`
- `src/commands/artifact-get.ts`

---

---
title: "Reflect workflow"
description: "Gather recent outcomes and dismissed signals, pattern thresholds, write learning and skill-proposal artifacts, and accept/reject proposals with git-backed skill diffs."
---

The reflect workflow is agent-driven through `skills/loopany-reflect/SKILL.md`: it queries the workspace via `loopany artifact list` / `get`, applies pattern thresholds before writing `learning` or `skill-proposal` artifacts, and completes skill changes only through proposal-apply (accept/reject) with `artifact append`, `artifact status`, and a git commit — never by editing `SKILL.md` files directly.

<Info>
Reflect is not a CLI subcommand. The harness supplies deterministic artifact I/O and graph edges; judgment (pattern detection, belief synthesis, scoped edits) stays in the agent skill.
</Info>

## Modes and routing

`loopany-resolver` routes these triggers to `loopany-reflect`:

| Trigger | Mode |
|---------|------|
| `reflect`, `what have we learned`, `improve yourself`, ≥3 tasks done recently | Reflect (discover → write) |
| `accept <proposal-slug>`, `reject <proposal-slug>`, `review proposals` | Proposal apply |
| Writing a `learning` or `skill-proposal` from any source | Reflect (creation rules) |

Cross-skill chaining: capture may suggest reflect after ≥3 captures in a session; weekly review suggests reflect after ≥3 resolutions. Learning `checkAt` revalidation belongs in `loopany-review` (daily), not reflect.

```mermaid
sequenceDiagram
  participant User
  participant Resolver as loopany-resolver
  participant Reflect as loopany-reflect
  participant CLI as loopany CLI
  participant Store as artifacts + references.jsonl
  participant Git as git (skills/)

  User->>Resolver: reflect / accept proposal
  Resolver->>Reflect: load SKILL.md
  alt Reflect mode
    Reflect->>CLI: artifact list / get
    CLI->>Store: indexed + body reads
    Reflect->>Reflect: pattern thresholds
    Reflect->>CLI: artifact create (learning, skill-proposal)
    Reflect->>CLI: refs add / trace (optional)
  else Proposal apply
    Reflect->>CLI: artifact get / refs
    Reflect->>Git: edit target SKILL.md (accept only)
    Reflect->>CLI: artifact append Outcome
    Reflect->>CLI: artifact status accepted|rejected
    Reflect->>Git: commit skill + proposal artifact
  end
```

## When to run reflect

Run reflect when:

- The user explicitly asks to reflect or improve the agent.
- Weekly cadence (structural mission review stays in `loopany-review` monthly).
- At least three tasks have flipped to `done` in a short window.

<Warning>
Do not run reflect reactively after every single task. `test/skill-regression.sh` scenario 8 expects agents to decline creating a `learning` when fewer than three completed tasks with outcomes exist.
</Warning>

## Step 1 — Gather evidence

List candidates, then narrow by recency and deduplication.

<Steps>
<Step title="List artifact pools">

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

`artifact list` returns a JSON array of `{ id, kind, path, frontmatter }`. With `--kind`, other flags map to frontmatter fields; fields listed in the kind’s `indexedFields` use O(1) index lookup (`status`, `targetSkill`, `checkAt`, etc.).

</Step>
<Step title="Filter to recent window">

Sort by `createdAt` (newest first). Default window ≈ one week.

</Step>
<Step title="Subtract already-processed evidence">

Union `evidence` from active learnings and non-rejected skill-proposals; exclude those artifact IDs from new pattern candidates.

</Step>
<Step title="Load bodies">

For each fresh candidate:

```bash
loopany artifact get <id>
# or --format json for frontmatter + body + audit history
```

Task evidence must include `## Outcome` before terminal `done`/`failed` (kind playbook; append before status flip).

</Step>
</Steps>

Optional body filter when the candidate set is still large:

```bash
loopany artifact list --kind task --status done --contains "baseline"
```

`--contains` runs last and scans bodies (and string frontmatter) case-insensitively.

## Step 2 — Pattern thresholds

Reflect only promotes **patterns**, not single anecdotes.

| Pattern | Threshold |
|---------|-----------|
| Same class of outcome | ≥ 3 tasks |
| Belief refuted | ≥ 2 tasks where an active learning predicts wrong |
| Belief needs caveat | ≥ 2 tasks |
| Signal dismissed but recurs | ≥ 3 dismissals over ≥ 2 weeks |

Good example: four metric tasks ship without `## Before` baselines → learning that outcomes are unfalsifiable → proposal requiring `## Before` in the task playbook.

Bad example: one failed outcome → no learning. A proposal whose change was already `rejected` → do not re-suggest.

## Step 3 — Write a learning

Beliefs live in `learning` artifacts (`skills/loopany-core/kinds/learning.md`). Title is the declarative belief; behavior change is optional and goes through `skill-proposal`.

<ParamField body="--kind" type="learning" required>
</ParamField>
<ParamField body="--slug" type="string" required>
Stable id for heavy `[[wiki-link]]` citation.
</ParamField>
<ParamField body="--title" type="string" required>
The belief sentence itself.
</ParamField>
<ParamField body="--evidence" type="string[]" required>
Comma-separated artifact slugs; minimum two IDs per playbook.
</ParamField>
<ParamField body="--check-at" type="date">
Revalidation date, typically 1–3 months out.
</ParamField>
<ParamField body="--mentions" type="string[]">
Soft links (also creatable via body `[[id]]`).
</ParamField>

<RequestExample>

```bash
loopany artifact create --kind learning \
  --slug short-attention-spans-2026 \
  --title "Metric tasks without baselines produce unfalsifiable outcomes" \
  --evidence "tsk-alpha,tsk-beta,tsk-gamma" \
  --mentions "mission-default" \
  --check-at 2026-07-22 \
  --content "$(cat <<'EOF'
## Observation
Four completed metric tasks recorded outcomes without before/after evidence.

## Evidence
- tsk-alpha — "Latency improved"
- tsk-beta — "Conversion up"
- tsk-gamma — "No baseline captured"

## Scope
Applies to quantitative tasks; not exploratory spikes.

## Check-at
On 2026-07-22: did new metric tasks include ## Before?
EOF
)"
```

</RequestExample>

Required body sections: `## Observation`, `## Evidence`, `## Scope`, `## Check-at`.

Status machine: `active` → `superseded` | `archived`. When understanding changes, **create a new learning** — do not edit the old file in place.

### Supersede an older belief

```bash
loopany refs add --from <new-learning> --to <old-learning> --relation supersedes
loopany artifact status <old-learning> superseded --reason "superseded by <new-learning>"
```

Append `## Outcome` to the superseded learning when flipping to `superseded` (kind required-sections rule; enforced by agent discipline).

## Step 4 — Write a skill-proposal (optional)

Create a proposal only when the learning implies a **concrete** `SKILL.md` edit. Many learnings stop at updated belief.

<ParamField body="--kind" type="skill-proposal" required>
</ParamField>
<ParamField body="--target-skill" type="string" required>
Path to `SKILL.md` (existing for `modify`/`remove`; planned path for `add`).
</ParamField>
<ParamField body="--change-type" type="enum" default="modify">
`modify` | `remove` | `add`
</ParamField>
<ParamField body="--evidence" type="string[]">
Citing tasks and/or the backing learning slug.
</ParamField>
<ParamField body="--check-at" type="date">
Schedules “did this change help?” review after accept.
</ParamField>

Required body sections:

1. `## Motivation` — cite the learning
2. `## Proposed change` — target file, intent, location, approximate content
3. `## Expected effect` — short- and long-term
4. `## Check-at` — why that date

For `changeType: add`, also include `## Skill draft` (full new `SKILL.md`) and `## Resolver entry` (row for `skills/loopany-resolver/SKILL.md`) or the skill is unreachable.

Status machine:

```mermaid
stateDiagram-v2
  [*] --> pending
  pending --> accepted: human accept + Outcome
  pending --> rejected: human reject + Outcome
```

CLI enforces transitions (`artifact status`); terminal `accepted`/`rejected` require `## Outcome` in the body per kind definition.

## Step 5 — Verify evidence chain

```bash
loopany trace <proposal-slug> --direction backward
```

Default trace relations: `led-to`, `addresses`, `supersedes`, `follows-up`, `cites` (excludes soft `mentions`). Output: `{ root, nodes[{ id, kind, distance }], edges[] }` sorted cause → root → effect.

To read explicit learning links on a proposal:

```bash
loopany refs <proposal-slug> --direction out --relation mentions
```

## Proposal apply (accept / reject)

Agents never patch skills outside this flow.

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

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

</Step>
<Step title="Accept">

1. `loopany artifact get <proposal-slug>`
2. `loopany refs <proposal-slug> --direction out --relation mentions` → cited learning
3. Read current `targetSkill` file
4. Apply **only** the described change
5. `loopany artifact append <proposal-slug> --section Outcome --content "..."`
6. `loopany artifact status <proposal-slug> accepted --reason "..."`
7. Git commit the skill file and proposal artifact together

</Step>
<Step title="Reject">

1. Read proposal
2. `loopany artifact append <proposal-slug> --section Outcome --content "<reason>"` (future reflect reads this)
3. `loopany artifact status <proposal-slug> rejected --reason "..."`

</Step>
</Steps>

### Accept edge cases

| Condition | Action |
|-----------|--------|
| Target `SKILL.md` missing | Reject |
| Cited learning `superseded` | Reject |
| Multiple pending proposals same file | Accept one at a time; re-read target between |

<Check>
Accepted or rejected proposals must have a non-empty `## Outcome` before status flip — empty outcomes break the self-improvement audit trail.
</Check>

## CLI surfaces reflect depends on

| Command | Role in reflect |
|---------|-----------------|
| `artifact list` | Evidence pools, dedup, pending proposals |
| `artifact get` | Outcomes, motivations, audit (`--format json`) |
| `artifact create` | New `learning` / `skill-proposal` |
| `artifact append` | `## Outcome` on accept/reject |
| `artifact status` | `accepted`/`rejected`/`superseded`; illegal transitions error |
| `refs add` / `refs` | `supersedes`, `mentions` |
| `trace` | Backward evidence chain |

<Note>
Kind required sections (`## Outcome` on terminal statuses) are declared in `skills/loopany-core/kinds/*.md` and enforced by agent workflow; `artifact status` enforces the status machine but does not yet parse body sections in TypeScript.
</Note>

## Anti-patterns

| Don't | Do instead |
|-------|------------|
| Reflect on one task | Wait for threshold table |
| Skip fresh-evidence filter | Union prior `evidence` fields first |
| `skill-proposal` without learning | Create learning first |
| Re-propose rejected change | Read `--status rejected` list |
| Edit `SKILL.md` directly | Proposal → accept → commit |
| Edit beyond proposal scope | Proposal body is the contract |
| Accept without reading learning | Verify scope against evidence |
| Run learning `checkAt` closure here | Use `loopany-review` daily + `followups` |

## Quick reference

```text
REFLECT:  list/get evidence → pattern? → learning → (optional) skill-proposal → user
ACCEPT:   get spr → refs → edit target → append Outcome → status accepted → git commit
REJECT:   get spr → append Outcome (reason) → status rejected
```

## Related pages

<CardGroup>
<Card title="Self-improvement loop" href="/self-improvement-loop">
End-to-end model: task outcomes, beliefs, proposals, and the no-direct-skill-edits rule.
</Card>
<Card title="Self-improvement example" href="/self-improvement-example">
Worked recipe from three done tasks through accept and git diff.
</Card>
<Card title="Skills library" href="/skills-library">
Resolver routing and reflect skill placement in the pack.
</Card>
<Card title="Kinds and validation" href="/kinds-and-validation">
`learning` and `skill-proposal` schemas, status machines, indexed fields.
</Card>
<Card title="Artifact commands" href="/artifact-commands">
`create`, `append`, `status`, `--slug`, `--content-file` details.
</Card>
<Card title="Reference graph" href="/reference-graph">
`refs`, `trace`, relation verbs including `supersedes` and `cites`.
</Card>
<Card title="Periodic review" href="/periodic-review">
Daily `checkAt` and weekly feed into reflect; scope boundaries.
</Card>
</CardGroup>