Operational Framework#

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.

ActionExample Shell / Pseudo‑CommandLog decisionecho '{...}' >> decisions/$(date +%F).jsonCreate snapshot./snapshot.sh <name> (your wrapper script)List snapshotsls -1 rollbacks/Restore snapshot./restore.sh <name>Generate briefing./brief.sh <decision‑id>Open TODOvim 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