Skip to content

Session Improvement Loop

The session improvement loop is ORCA Framework's built-in way to learn from real usage friction. It now feeds two distinct loops: local instance improvement and framework improvement.

At the end of a meaningful session, ORCA Framework should briefly review the work and ask a narrow question:

Did this session expose a reusable ORCA Framework problem that should become backlog work?

If the answer is yes, ORCA Framework should turn that friction into a structured improvement note, check whether it is worth an issue, look for overlap, and ask the user before drafting or submitting a GitHub issue to the ORCA Framework repository. One of the main review questions is whether ORCA Framework reduced drag or added it. Another is whether one lightweight coaching hint could have helped the user without sounding blameful. Another is whether the signal should stay local, become a framework candidate, or just be watched.

Purpose

Use the loop to catch:

  • framework gaps
  • rough edges
  • missing commands or templates
  • confusing docs
  • runtime mismatches
  • repeated manual workarounds
  • weak automation
  • repeated install confusion or setup drop-off
  • repeated update confusion, risky update surprises, or broken rollback paths
  • host-specific friction that should change the framework
  • avoidable setup work or option sprawl
  • a gentle next-time note when it would reduce repeated user friction
  • orchestration splits that added complexity without enough leverage
  • session-quality signals that indicate low trust, generic output, repeated wrong direction, or poor failure handling

What It Is Not

This loop is not:

  • a complaint collector
  • a mandatory long retrospective after every tiny task
  • permission to open external issues automatically
  • a way to mix product bugs with framework improvement work

When It Runs

Run the loop at the end of:

  • a meaningful implementation session
  • a QA-heavy session
  • a blocked or confusing session
  • a background run that exposed friction
  • a review, replay, or restore session that showed framework weaknesses

Skip or stay quiet when:

  • the session was trivial
  • the friction was clearly one-off
  • the issue is already known and no new evidence was added
  • the candidate is really a project-specific problem rather than a framework problem

Loop Stages

  1. Brief session review
  2. Quality-signal triage
  3. Local vs framework loop classification
  4. Improvement candidate capture
  5. Issue-worthiness check
  6. Duplicate and overlap check
  7. Human approval prompt
  8. Draft issue or submit issue
  9. Record candidate or link in the improvement backlog

Human Approval Rule

No external issue submission should happen without explicit user approval.

Allowed actions:

  • skip
  • draft only
  • submit now
  • merge into an existing issue
  • remind later

Core Artifacts