Skip to content

Frappucc1no/recall-loom / skills/recallloom

recallloom

Flagged

Use when a task involves continuing a project, restoring project context, maintaining file-based project memory, updating current-state summaries, or recording meaningful progress across sessions. Works best for long-horizon, file-based projects and supports research writing, product document collaboration, software project coordination, and broader cross-functional project continuity.

FileKindSize
LICENSEother10.0 KB
NOTICEother190 B
SKILL.mdskill md24.5 KB
managed-assets.jsonconfig1.1 KB
native_commands/README.mdmarkdown1.2 KB
native_commands/claude-code/rl-init.md.tmplother323 B
native_commands/claude-code/rl-resume.md.tmplother290 B
native_commands/claude-code/rl-status.md.tmplother299 B
native_commands/claude-code/rl-validate.md.tmplother277 B
native_commands/gemini-cli/rl-init.toml.tmplother295 B
native_commands/gemini-cli/rl-resume.toml.tmplother262 B
native_commands/gemini-cli/rl-status.toml.tmplother271 B
native_commands/gemini-cli/rl-validate.toml.tmplother249 B
native_commands/opencode/rl-init.md.tmplother286 B
native_commands/opencode/rl-resume.md.tmplother253 B
native_commands/opencode/rl-status.md.tmplother262 B
native_commands/opencode/rl-validate.md.tmplother240 B
package-metadata.jsonconfig1.0 KB
profiles/general-project-continuity.mdmarkdown2.4 KB
profiles/product-doc-collaboration.mdmarkdown2.2 KB
profiles/research-writing.mdmarkdown2.1 KB
profiles/software-project-coordination.mdmarkdown2.8 KB
references/anti-patterns.mdmarkdown2.5 KB
references/contract-registry.jsonconfig7.7 KB
references/contract-schema.jsonconfig7.7 KB
references/file-contracts.mdmarkdown23.4 KB
references/operation-playbooks.mdmarkdown26.5 KB
references/package-support-policy.mdmarkdown9.4 KB
references/profiles.mdmarkdown2.0 KB
references/protocol.mdmarkdown20.5 KB
references/recording-workflow.mdmarkdown9.9 KB
scripts/_common.pyscript87.8 KB
scripts/append_daily_log_entry.pyscript40.4 KB
scripts/archive_logs.pyscript17.6 KB
scripts/commit_context_file.pyscript31.6 KB
scripts/core/__init__.pyscript39 B
scripts/core/bridge/__init__.pyscript30 B
scripts/core/bridge/blocks.pyscript6.9 KB
scripts/core/coldstart/__init__.pyscript26 B
scripts/core/coldstart/sources.pyscript22.4 KB
scripts/core/coldstart/structured.pyscript5.4 KB
scripts/core/continuity/__init__.pyscript34 B
scripts/core/continuity/daily_log.pyscript16.1 KB
scripts/core/continuity/freshness.pyscript15.3 KB
scripts/core/continuity/preflight.pyscript41.0 KB
scripts/core/continuity/quick_summary.pyscript10.9 KB
scripts/core/continuity/workday.pyscript12.3 KB
scripts/core/errors.pyscript838 B
scripts/core/failure/__init__.pyscript47 B
scripts/core/failure/context.pyscript5.6 KB
scripts/core/failure/contracts.pyscript108.6 KB
scripts/core/output/__init__.pyscript35 B
scripts/core/output/confirmation_material.pyscript15.0 KB
scripts/core/output/privacy.pyscript10.5 KB
scripts/core/output/user_status.pyscript5.8 KB
scripts/core/protocol/__init__.pyscript60 B
scripts/core/protocol/contracts.pyscript8.3 KB
scripts/core/protocol/markers.pyscript4.9 KB
scripts/core/protocol/sections.pyscript3.4 KB
scripts/core/protocol/templates.pyscript6.5 KB
scripts/core/provenance/__init__.pyscript67 B
scripts/core/provenance/bindings.pyscript13.2 KB
scripts/core/provenance/evidence.pyscript58.2 KB
scripts/core/provenance/inconsistent_review.pyscript85.6 KB
scripts/core/provenance/receipts.pyscript20.2 KB
scripts/core/provenance/state.pyscript38.0 KB
scripts/core/provenance/store.pyscript43.8 KB
scripts/core/recording/__init__.pyscript1.6 KB
scripts/core/recording/contracts.pyscript31.7 KB
scripts/core/recording/daily_log_append.pyscript30.2 KB
scripts/core/recording/managed_write.pyscript52.8 KB
scripts/core/recording/planner.pyscript20.6 KB
scripts/core/recording/privacy.pyscript1.7 KB
scripts/core/recording/suggestions.pyscript8.6 KB
scripts/core/recording/transaction.pyscript93.3 KB
scripts/core/registry/__init__.pyscript58 B
scripts/core/registry/loader.pyscript18.8 KB
scripts/core/safety/__init__.pyscript30 B
scripts/core/safety/attached_text.pyscript6.9 KB
scripts/core/safety/input_transport.pyscript61.0 KB
scripts/core/safety/prepared_input.pyscript24.4 KB
scripts/core/safety/scratch_residue.pyscript18.8 KB
scripts/core/support/__init__.pyscript53 B
scripts/core/support/cache.pyscript19.4 KB
scripts/core/support/policy.pyscript8.8 KB
scripts/core/trust/__init__.pyscript42 B
scripts/core/trust/state.pyscript4.1 KB
scripts/core/workspace/__init__.pyscript33 B
scripts/core/workspace/atomic_io.pyscript12.2 KB
scripts/core/workspace/runtime.pyscript54.7 KB
scripts/detect_project_root.pyscript3.4 KB
scripts/generate_coldstart_proposal.pyscript7.5 KB
scripts/init_context.pyscript37.8 KB
scripts/install_native_commands.pyscript31.5 KB
scripts/manage_entry_bridge.pyscript20.8 KB
scripts/preflight_context_check.pyscript10.1 KB
scripts/prepare_recovery_promotion.pyscript22.1 KB
scripts/query_continuity.pyscript84.1 KB
scripts/recallloom.pyscript233.7 KB
scripts/recommend_workday.pyscript17.6 KB
scripts/record_recovery_review.pyscript50.9 KB
scripts/remove_context.pyscript13.9 KB
scripts/repair_daily_log_cursor.pyscript33.7 KB
scripts/stage_recovery_proposal.pyscript17.5 KB
scripts/summarize_continuity_status.pyscript43.7 KB
scripts/sync_contract_docs.pyscript11.3 KB
scripts/unlock_write_lock.pyscript8.1 KB
scripts/validate_context.pyscript54.9 KB

references/recording-workflow.md

View on GitHub
# Recording Workflow

`record --plan` is the side-effect-free recording fast lane.

It classifies a recording intent, returns an ordered helper path, and points to the current safe next step or a stop/ask reason. It does not write sidecar files, daily logs, receipts, locks, derived evidence, or revisions.

`record --suggest` is the side-effect-free proactive prompt lane.

It reviews public-safe candidate text and returns one of three outcomes:

- `candidate`: show a sanitized candidate summary and suggested `record --plan` path.
- `silent`: do not prompt because the text is exploratory, unstable, or explicitly says not to record.
- `blocked`: do not suggest a write path because the candidate looks sensitive or private.

It does not run in the background, watch files, auto-listen, write sidecar files, or approve a later record action.

## Command Shape

Append-only progress:

```bash
recallloom.py record <project> --plan \
  --intent-text "record this progress" \
  --payload-json '{"entry_kind":"milestone","payload_ref":"redacted"}' \
  --layer-hint daily-log \
  --privacy-safety-json '{"classification":"safe"}' \
  --json
```

Compact output:

```bash
recallloom.py record <project> --plan \
  --intent-text "record this progress" \
  --payload-json '{"entry_kind":"milestone","payload_ref":"redacted"}' \
  --layer-hint daily-log \
  --privacy-safety-json '{"classification":"safe"}' \
  --compact --json
```

Proactive suggestion:

```bash
recallloom.py record <project> --suggest \
  --intent-text "completed a public-safe milestone" \
  --privacy-safety-json '{"classification":"safe"}' \
  --json
```

## Input Contract

`record --plan` and `record --suggest` accept these input fields through CLI options:

- `intent_text`: original user or agent intent.
- `prepared_record_payload`: public-safe structured payload or placeholder reference.
- `optional_layer_hint`: one of `daily_log`, `current_state`, `stable_context`, `protocol_rule`, `metadata`.
- `privacy_safety_result`: public-safe object such as `{"classification":"safe"}` or `{"classification":"unsafe"}`.
- `expected_revision_binding`: optional revision binding object; preflight binding is attached by the dispatcher.
- `semantic_unchanged_assertion`: required by metadata-only summary refresh flows that reuse the current managed body.

Do not put raw private payloads, shell transcripts, absolute local paths, reserved RecallLoom markers, manual patches, or direct `state.json` / `config.json` edits into the payload or retry template.

## Prepared Input Templates

These templates show valid prepared shapes. Replace placeholder text with public-safe project content only, then use the dispatcher so it can run a fresh preflight and issue the revision binding before any mutation.

Append daily-log JSON:

```bash
recallloom.py append <project> \
  --entry-json '{"work_completed":["public-safe milestone"],"confirmed_facts":["public-safe fact"],"key_decisions":["none"],"risks_blockers":["none"],"recommended_next_step":["next safe step"]}' \
  --input-format json \
  --json
```

Append daily-log markdown:

```markdown
<!-- section: work_completed -->
- public-safe milestone

<!-- section: confirmed_facts -->
- public-safe fact

<!-- section: key_decisions -->
- None.

<!-- section: risks_blockers -->
- None.

<!-- section: recommended_next_step -->
- next safe step
```

Current-state JSON:

```bash
recallloom.py write <project> \
  --type current-state \
  --source-file <prepared-current-state.json> \
  --input-format json \
  --dry-run \
  --json
```

```json
{
  "current_state": "public-safe current state",
  "active_judgments": [],
  "risks_open_questions": [],
  "next_step": "next safe step",
  "recent_pivots": []
}
```

The JSON block is the complete UTF-8 content of
`<prepared-current-state.json>`. Remove `--dry-run` only after the dispatcher
has returned a fresh preflight result that authorizes the write.

## Dispatcher Internal Helper Boundary

For normal operations, use only the applicable dispatcher surface. Managed-file
writes and daily-log entries use `write` and `append`;
`sync-current-state-after-append` is used only when its post-append contract
requires that lane. `commit_context_file.py` and `append_daily_log_entry.py` are
internal dispatcher and integration surfaces, not standalone operator paths.
The dispatcher runs a fresh preflight, constructs the binding, and writes the
matching lease immediately before calling a helper. A read-only
`preflight_context_check.py <project> --json` result does not issue either
material. There is no independent operator binding/lease pickup interface: a
hand-invoked helper without the still-current dispatcher-issued material is
expected to fail. Never reconstruct, copy from preflight output, reuse, or
amend that material.

After a D5 promotion produces `review_imported_baseline`, use dispatcher
`write` or `append` with its existing `--confirm-review-imported-baseline` flag
for the first write. The dispatcher then issues the
confirmation-bound binding and matching lease. The internal helpers do not accept
that flag; the internal helpers only verify and consume the dispatcher-issued binding and lease
inside the dispatcher/integration path.
The existing `sync-current-state-after-append` lane also accepts the confirmation
when its own post-append contract requires it; it still delegates through the
same internal binding/lease boundary.

The three dispatcher mutation commands (`append`, `write`, and
`sync-current-state-after-append`) also accept `--compact-json` for the bounded
`recallloom.transaction.compact/1.0` result. It is mutually exclusive with
legacy `--json`, preserves the exit code, contains exactly one safe next action,
and must remain below 2048 UTF-8 bytes.
If the binding is omitted, stale, malformed, missing its lease or confirmation,
or has a mismatched hash, stop and return the helper failure contract rather
than attempting a write.

Record-plan input:

```json
{
  "intent_text": "record public-safe progress",
  "prepared_record_payload": {
    "entry_kind": "milestone",
    "payload_ref": "redacted"
  },
  "optional_layer_hint": "daily_log",
  "privacy_safety_result": {
    "classification": "safe"
  }
}
```

Failure retry template:

```json
{
  "first_step": "rerun_preflight_or_status",
  "project_ref": "same_project",
  "input_ref": "same_public_safe_prepared_input",
  "do_not_reuse": [
    "stale_revision_binding",
    "free_text_semantic_confirmation",
    "raw_private_payload"
  ]
}
```

## Metadata-Only Refresh Assertion

Use metadata-only refresh only after preflight allows `post_append_summary_sync` and returns an assertion binding seed. The assertion JSON is bound data, not a free-text confirmation:

Before `record --plan` may expose the metadata-refresh helper path, the plan input must explicitly include `--semantic-unchanged`. If that decision is omitted, the plan remains confirmation-only with no current safe command. If meaning changed, use `--semantic-changed` and route to a separately reviewed current-state update instead.

```json
{
  "semantic_unchanged": true,
  "assertion_source_kind": "record_plan_output_id",
  "assertion_source_id": "record-plan-output:sha256:<64hex>",
  "input_digest": "sha256:<64hex>",
  "record_plan_output": {
    "record_plan_output_id": "record-plan-output:sha256:<64hex>",
    "input_digest": "sha256:<64hex>",
    "...": "complete record --plan JSON output"
  },
  "assertion_binding_seed": {
    "assertion_kind": "post_append_summary_metadata_only_semantic_unchanged",
    "expected_workspace_revision": 0,
    "expected_file_revision": 0,
    "summary_base_workspace_revision": 0,
    "latest_daily_log_entry_id": "entry-1",
    "latest_daily_log_entry_seq": 1,
    "latest_daily_log_entry_created_at": "YYYY-MM-DDTHH:MM:SSZ",
    "latest_daily_log_entry_date": "YYYY-MM-DD",
    "latest_daily_log_entry_hash": "sha256:<64hex>",
    "latest_daily_log_digest": "sha256:<64hex>",
    "body_digest_before": "sha256:<64hex>"
  },
  "assertion_binding_seed_digest": "sha256:<64hex>"
}
```

`source_id` is not accepted. `record_plan_output_id` assertions must carry the complete `record_plan_output` so the helper can recompute its id, input digest, and preflight binding before any metadata-only refresh. `explicit_operator_confirmation` is also allowed only when it carries the same bound fields and uses an `assertion_source_id` shaped like `explicit-operator-confirmation:sha256:<64hex>`. Do not use a bare `semantic_unchanged: true` boolean or free-text confirmation.

## Output Meaning

For `record --suggest`:

- `suggestion_status`: `candidate`, `silent`, or `blocked`.
- `should_prompt`: `true` only when the user should see a sanitized candidate recording prompt.
- `candidate_summary`: sanitized text only; sensitive candidates use a redacted digest reference instead.
- `suggested_path`: a suggested `record --plan` path only, never a write command.
- `side_effect`: always `none`.

Important fields:

- `workflow_status`: `ready_to_run`, `needs_user_confirmation`, `blocked_fixable`, `blocked_unsafe`, `no_write`, or `complete`.
- `record_class`: `append_only`, `current_state_update`, `stable_context_update`, `protocol_rule_update`, `simple_multi_layer_plan`, `metadata_refresh_only`, `amend_last`, `duplicate_noop`, `defer_no_write`, `no_write_success`, `ambiguous_needs_user`, or `unsafe_blocked`.
- `current_safe_command`: one helper command to run now, or `null` when the plan must ask/stop/no-op.
- `ordered_executable_path`: the reviewed order for helper commands; multi-layer plans may include a path while keeping `current_safe_command` null until the user confirms.
- `side_effect`: always `none` for `record --plan`.
- `record_plan_output_id` and `input_digest`: stable digests for downstream validation.

## Retry Rule

If `current_safe_command` is null:

- `needs_user_confirmation`: ask one clear question before writing.
- `blocked_unsafe`: stop and remove/redact unsafe input.
- `no_write` or `complete`: do not write; report the reason.
- `blocked_fixable`: retry only with the public-safe template returned by the helper.
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall