superdesigndev/loopany/loopany-reflect

loopany-reflect — self-improvement loop

Two modes: reflect (discover patterns → write learnings + proposals) and proposal-apply (accept or reject a pending proposal).

Part 1: Reflect

When to run

• User asks: "reflect", "what have we learned", "improve yourself"
• Weekly cadence (monthly structural review → loopany-review)
• After ≥ 3 tasks flip to done in a short window

Don't run reactively after every single task.

Step 1 — Gather evidence

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

Filter to recent by createdAt (newest first). Default window ≈ 1 week.

Filter out already-processed evidence. Union evidence fields from active learnings and non-rejected proposals → subtract from candidates.

Exception: learning revalidation on checkAt belongs in loopany-review § Daily, not here. Reflect looks forward; daily review looks back.

For each fresh candidate: loopany artifact get <id>

Step 2 — Look for patterns

Good: 4 metric tasks without baselines → learning about unfalsifiable outcomes → proposal to require ## Before. Bad: 1 bad outcome → not a pattern. Already-rejected proposal → don't re-suggest.

Step 3 — Write a learning

→ See ../loopany-core/kinds/learning.md § Playbook for schema.

loopany artifact create --kind learning \
  --slug short-attention-spans-2026 \
  --title "<declarative belief sentence>" \
  --evidence "<task-slug-1>,<task-slug-2>" \
  --mentions "<mission-slug>" \
  --check-at 2026-07-22 \
  --content "$(cat <<'EOF'
## Observation
<what you saw across evidence>
 
## Evidence
- <task-slug-1> — "<outcome summary>"
- <task-slug-2> — "<outcome summary>"
 
## Scope
<when this applies and doesn't>
 
## Check-at
<why this date; what question to answer>
EOF
)"

Key fields: title = belief itself, evidence ≥ 2 IDs, checkAt 1-3 months. Always --slug learnings — they get [[cited]] a lot.

Step 4 — Write a skill-proposal (if warranted)

Only if the learning implies a concrete skill edit. Many learnings stop at "now I know."

→ See ../loopany-core/kinds/skill-proposal.md for schema.

Required body sections:

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

When `changeType: add` (new skill):

• --target-skill = to-be-created path
• ## Proposed change must name existing skills considered and why rejected
• Add ## Skill draft (full SKILL.md with frontmatter) + ## Resolver entry

Step 5 — Verify evidence chain

loopany trace <proposal-slug> --direction backward

If learning supersedes an older one:

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

Part 2: Proposal Apply

When to run

• "accept <proposal-slug>", "reject <proposal-slug>", "let's take that proposal"
• Batch review of pending proposals

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

Accept flow

1. Read proposal: loopany artifact get <proposal-slug>
2. Read cited learning: loopany refs <proposal-slug> --direction out --relation mentions
3. Read current target file
4. Apply edit faithfully — only the described change
5. Append ## Outcome to proposal (what literally changed, interpretations)
6. Flip status: loopany artifact status <proposal-slug> accepted --reason "..."
7. Git commit: target file + proposal together

Reject flow

1. Read proposal
2. Append ## Outcome with reason — future reflect reads this
3. Flip status: loopany artifact status <proposal-slug> rejected --reason "..."

Edge cases

• Target file doesn't exist → reject
• Cited learning superseded → reject
• Multiple proposals same file → accept one at a time, re-read between

Anti-patterns

• ❌ Reflecting on single task — not a pattern.
• ❌ Skipping fresh-evidence filter — produces duplicates.
• ❌ Proposing without a learning — no evidence trail.
• ❌ Re-suggesting rejected proposal — check list first.
• ❌ add without ## Resolver entry — dead code.
• ❌ Trigger phrases in jargon — mirror real user language.
• ❌ Editing skill file directly — always go through proposals.
• ❌ Editing beyond proposal scope — the proposal is the contract.
• ❌ Accept without reading learning — can't verify scope.
• ❌ Empty Outcome on accept/reject.

Quick reference

REFLECT:  evidence → pattern → learning → (optional) proposal → user accept → edit
ACCEPT:   read spr → read lrn → read target → edit → Outcome → status → commit
REJECT:   read spr → Outcome (with reason) → status