# REFINE_Project

> REFINE is an adaptive skill engine for structured session diagnostics. Use this skill when a user explicitly requests: logging error patterns across sessions, maintaining session memory, generating System Prompt Patches from failure analysis, or structured feedback capture on ClawHub or SkillPay. Activate for requests about "error logging", "session memory", "patch synthesis", or "adaptive skill logging". Do not activate for general conversation or unrelated tasks.

- Skill: `lord1egypt/refine-project` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/refine-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/refine-project/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT-0
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/refine-project

---


# REFINE — Adaptive Session Diagnostics

A dual-mode skill engine. Captures error patterns and feedback labels locally,
then (in PRO mode) synthesises System Prompt Patches from local failure analysis.

All data stays on local disk (`refine_memory.json`). No network calls are made.

---

## What Gets Stored — Complete List

All caller-supplied data passes through sanitization before reaching disk.

| Source | Field | Sanitization applied |
|---|---|---|
| `capture_feedback(feedback)` | `feedback` | Truncated to 300 chars |
| `capture_feedback(context)` | `context` | See Context Sanitization below |
| `log_error(error)` | `type` | Exception class name only |
| `log_error(error)` | `message` | First line only, truncated 300 chars |
| `log_error(context)` | `context` | See Context Sanitization below |
| Stack traces | — | **Never stored** |
| Raw prompts | — | **Never stored** |

### Context Sanitization — Enforced by Code

The `context` dict argument in both `capture_feedback()` and `log_error()`
is passed through `_sanitize_context()` before any write. This function:

1. **Blocks sensitive key names** — keys matching `token`, `key`, `secret`,
   `password`, `auth`, `api_key`, `bearer`, `credential`, `private`, `seed`,
   `hash`, `pin`, `ssn`, `credit`, `card`, `cvv` → stored as
   `[REDACTED — sensitive key name]`
2. **Rejects nested objects** — any `dict` or `list` value →
   `[REMOVED — nested dict/list not stored]`
3. **Truncates strings** — all string values capped at 200 chars
4. **Limits keys** — maximum 8 keys per context dict
5. **Scalar types only** — `str`, `int`, `float`, `bool` permitted;
   all other types → `[REMOVED — unsupported type]`

This is a **code-level enforcement** — it applies regardless of warnings
in documentation. Sensitive data cannot reach the JSON file.

---

## Mode Selection

`REFINE_MODE` is optional — defaults to `BASIC` if not set.

| `REFINE_MODE` | Platform | Tier | Auth required |
|---|---|---|---|
| `BASIC` (default) | ClawHub | Free | None |
| `PRO` | SkillPay | Paid | `SKILLPAY_TOKEN_HASH` + header |

```bash
# BASIC — no configuration needed
python main.py

# PRO — set both variables
export REFINE_MODE=PRO
export SKILLPAY_TOKEN_HASH=$(echo -n "your-token" | sha256sum | cut -d' ' -f1)
```

---

## BASIC Mode

```python
from main import build_engine

engine = build_engine()

# Safe: short diagnostic labels only
engine.capture_feedback("verbosity-high", context={"prompt_id": "p001"})

# Context is sanitized — api_key below will be stored as [REDACTED]
engine.capture_feedback("test", context={"api_key": "sk-..."})   # → [REDACTED]

try:
    risky_operation()
except Exception as exc:
    engine.log_error(exc, {"endpoint": "/api/v1"})   # context sanitized

history = engine.get_history(limit=10)
engine.close()
```

---

## PRO Mode

```python
import os
from main import build_engine, SKILLPAY_HDR

token   = your_secret_manager.get("skillpay-token")
headers = {SKILLPAY_HDR: token}

engine = build_engine(auth_headers=headers)

report = engine.evolve()   # analyse local errors → synthesise patch
patch  = engine.get_latest_patch()
if patch:
    next_system_prompt = patch["patch_body"] + "\n\n" + base_system_prompt

engine.close()
```

---

## Security

| Concern | Implementation |
|---|---|
| Token comparison | `hmac.compare_digest` — stdlib `hmac`, constant-time |
| Token in logs | Never — 8-char hash prefix only |
| Token storage | `SKILLPAY_TOKEN_HASH` env var only |
| Context dicts | Sanitized by `_sanitize_context()` before any disk write |
| Sensitive keys | Blocked by regex — stored as `[REDACTED]` |
| Nested objects | Rejected — stored as `[REMOVED]` |
| String values | Truncated to 200 chars in context, 300 chars elsewhere |
| Stack traces | Never stored |
| Network calls | None — fully offline |
| File writes | Atomic temp-file rename |

---

## Environment Variables

All optional:

| Variable | Default | Description |
|---|---|---|
| `REFINE_MODE` | `BASIC` | `BASIC` or `PRO` |
| `SKILLPAY_TOKEN_HASH` | (none) | SHA-256 hex of token; PRO only |
| `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |