Operational Framework

A disciplined, reproducible workflow for AI agents to log decisions, create rollback snapshots, and generate briefings for any change or feature implementation.

A disciplined approach to implementing changes with full traceability.

When to Use

• Implementing improvements or new features
• Making configuration changes
• Any work that needs rollback capability
• Generating case study briefings

Architecture (generic)

text

<workspace>/
├── decisions/          # Decision logs (JSON per day)
│   └── <date>.json    # Example: 2026‑05‑08.json
├── rollbacks/         # Snapshot directories
│   └── <timestamp>/   # Example: 2026‑05‑08_2005/
├── briefings/         # Case‑study markdown files
│   └── <date>.md      # Example: 2026‑05‑08.md
└── TODO.md            # Persistent task list

Replace <workspace> with the root of your OpenClaw workspace (usually ~/.openclaw/workspace).

Decision Logging (generic)

Log each major decision before you start changing anything. Use a simple JSON schema:

json

{
  "id": "dec_<date>_<seq>",
  "timestamp": "<ISO‑8601>",
  "title": "<short description>",
  "context": "<why this decision matters>",
  "options_considered": ["<opt1>", "<opt2>", "<opt3>"],
  "chosen": "<selected option>",
  "reasoning": "<rationale>",
  "expected_outcome": "<what success looks like>",
  "risk_mitigation": "<how to handle failure>",
  "status": "pending|implemented|reverted"
}

How to log:

• Manually edit a file in decisions/ (e.g., 2026-05-08.json).
• Or, if you have a CLI wrapper, run:

text

/decide "<title>" --context "<ctx>" --options "opt1|opt2|opt3" --chosen "opt2" --reasoning "<reason>"

Replace placeholders with your actual values.

Rollback System (generic)

Take a lightweight snapshot before you modify anything. The snapshot can be a simple copy of files or a git commit.

Typical workflow:

1. Choose a name (e.g., 2026-05-08_2005).
2. Copy the relevant files or the whole workspace into rollbacks/<name>/.
3. Verify the copy.
4. If needed, restore by copying back.

Example (shell‑style, adapt to your environment):

bash

# Create snapshot directory
mkdir -p rollbacks/2026-05-08_2005
# Copy files you care about (or the whole workspace)
cp -r decisions rollbacks/2026-05-08_2005/
cp -r briefings rollbacks/2026-05-08_2005/
# ... add other paths as needed

Listing snapshots:

bash

ls -1 rollbacks/

Restoring:

bash

cp -r rollbacks/2026-05-08_2005/* <workspace>/

The exact commands can be wrapped in a script for convenience.

Implementation Workflow

1. Decision Phase

• Log the decision with full context
• Define success criteria
• Identify rollback strategy

2. Snapshot Phase

• Capture current state
• Verify snapshot integrity

3. Implementation Phase

• Execute change
• Document as you go
• Test incrementally

4. Verification Phase

• Does it meet success criteria?
• Any unexpected side effects?

5. Briefing Phase

• Generate case study
• Note what worked/didn't
• Update TODO if follow-ups needed

Briefing Format

markdown

# Implementation Briefing: [Title]
**Date:** YYYY-MM-DD
**Decision ID:** dec_YYYY-MM-DD_XXX

## Context
[What triggered this]

## Decision
[What was decided and why]

## Implementation
[How it was implemented]

## Outcome
[Success/failure with evidence]

## Lessons Learned
- What worked well
- What would do differently
- Patterns to propagate

## Rollback Point
[Reference to snapshot if needed]

Quick Commands (examples)

Below are illustrative commands you can bind to your own CLI or script. They are not built‑in OpenClaw commands, but they show the typical flow.

Action	Example Shell / Pseudo‑Command
Log decision	echo '{...}' >> decisions/$(date +%F).json
Create snapshot	./snapshot.sh <name> (your wrapper script)
List snapshots	ls -1 rollbacks/
Restore snapshot	./restore.sh <name>
Generate briefing	./brief.sh <decision‑id>
Open TODO	vim TODO.md

Feel free to adapt these to your preferred tooling (bash, Python, etc.).

TODO Integration

Maintain TODO.md in workspace root:

markdown

## 2026-05-08 Implementation Session

### Active
- [ ] Decision: Implement X
- [ ] Snapshot: AGENTS.md

### Completed
- [x] Decision: Add memory recall
- [x] Implemented: 2026-05-08
- [x] Briefing: briefings/2026-05-08.md

Key Principles

1. Log before acting - Decisions documented before implementation
2. Snapshot before change - Always have a rollback path
3. Brief after completion - Document for future reference
4. Never lose context - Everything survives session restarts

Integration

This framework integrates with:

• Self-Improving skill - Lessons feed into corrections.md
• HEARTBEAT.md - Periodic decision review
• AGENTS.md - Framework reference in operational procedures

Requirements

• No credentials required
• No extra binaries required
• Works with existing workspace structure