focusa

name	focusa
description	Use when preserving Focusa cognitive state, resuming after compaction/model switch/context overflow, linking evidence to Workpoints, using Focus State, work-loop, lineage/tree, metacognition, state-hygiene, or diagnosing Focusa tool readiness.

Focusa Cognitive Runtime Skill

Use this skill for any task where durable meaning matters more than transcript memory: multi-step implementation, compaction recovery, release proof, evidence capture, long-running work loops, reusable learning, or Focusa tool troubleshooting.

Skill loading rules

Pi skills must start with YAML frontmatter. Required fields:

---
name: focusa
description: Use when preserving Focusa cognitive state, resuming after compaction/model switch/context overflow, linking evidence to Workpoints, using Focus State, work-loop, lineage/tree, metacognition, state-hygiene, or diagnosing Focusa tool readiness.
---

If Pi reports:

[Skill conflicts]
~/.pi/skills/focusa/SKILL.md
  description is required

then the installed SKILL.md is missing/has invalid frontmatter. Repair the project source copy and the user runtime copy resolved from PI_SKILLS_DIR or $HOME/.pi/skills.

Validate with the portable harness:

node scripts/validate-skill-hygiene.mjs

Companion skills

The main focusa skill is the router/mental model. Load focused companion skills for deeper playbooks:

• /skill:focusa-workpoint — Workpoint checkpoint/resume/evidence/drift workflows.
• /skill:focusa-metacognition — reusable learning, reflection, adjustments, evaluation.
• /skill:focusa-work-loop — continuous work-loop writer/status/control workflows.
• /skill:focusa-cli-api — direct daemon/CLI/API release proof and troubleshooting.
• /skill:focusa-troubleshooting — offline/degraded/pending/blocked recovery.
• /skill:focusa-docs-maintenance — public docs, skill docs, evidence, snapshot wording.

Focused tool docs live under docs/focusa-tools/README.md.

Best-practice principles

Research/docs basis:

• Pi skill docs and Agent Skills spec: skills are progressive disclosure packages; name and description are always visible, full content loads on demand.
• Required frontmatter: name and description; name must match parent directory and use lowercase hyphen format.
• Description should be specific, include “when to use”, and stay below 1024 chars.
• Keep SKILL.md as a dispatcher: short core rules plus pointers to detailed docs/evidence.
• Use consistent family headings, concrete tool-selection rules, validation commands, and recovery paths.
• Avoid dumping raw logs or giant references into the skill; use evidence handles and docs paths.

Default pickup sequence

When uncertain, resumed, compacted, or after context overflow:

1. focusa_workpoint_resume — retrieve canonical/degraded continuation contract.
2. focusa_tool_doctor — diagnose daemon, active Workpoint, Focus State, and next repair.
3. focusa_active_object_resolve — resolve active object candidates without inventing canonical refs.
4. focusa_evidence_capture or focusa_workpoint_link_evidence — capture proof as handles and link to active Workpoint.
5. Use the task-specific family below.

If canonical=false or degraded=true, treat output as recovery hint only until a canonical read confirms it.

Focus State family

Use for compact cognitive state. Do not store raw transcripts here.

• focusa_scratch — working notes, reasoning, task lists, hypotheses, self-correction. Scratchpad only; not Focus State.
• focusa_decide — one crystallized architectural decision, max 280 chars; use after scratchpad reasoning.
• focusa_constraint — discovered hard requirement from operator/spec/API/environment.
• focusa_failure — specific failure plus diagnosis and recovery.
• focusa_intent — session mission/frame intent.
• focusa_current_focus — active work in 1–3 sentences.
• focusa_next_step — bounded next action.
• focusa_open_question — unresolved question.
• focusa_recent_result — completed result or evidence reference.
• focusa_note — small miscellaneous note; bounded and decays.

Validation discipline:

• Working notes never go into focusa_decide; put reasoning, task lists, failed wording, and retries in focusa_scratch.
• Decisions are architectural choices, not task lists or debug narratives.
• Constraints are discovered requirements, not agent commitments. Phrase constraints as declarative architecture boundaries: Workpoint continuity identity uses project_root plus continuity_id, not Need to fix... or Do not....
• If a Focus State write tool rejects validation, treat that as a phrasing error: save the detailed note to scratchpad, retry once with compliant noun-phrase wording, then continue without looping.
• Failures name the failing component and why.

Workpoint family

Use for continuity across compaction/resume/model switch/fork/risky work.

• focusa_workpoint_checkpoint — create typed checkpoint before discontinuity or risky continuation.
• focusa_workpoint_resume — fetch active WorkpointResumePacket; use immediately after compaction or uncertainty.
• focusa_workpoint_link_evidence — attach stable evidence refs/results to active canonical Workpoint.
• focusa_active_object_resolve — resolve likely active objects; returns candidates, not invented truth.
• focusa_evidence_capture — capture bounded evidence and optionally link to Workpoint.

Identity and isolation rules:

• project_root is the project folder/container: the place that holds the files related to the project.
• Navigation metaphor: project_root is the vessel/hull; better project-root confidence improves travel reliability, but it is not the functional route or destination.
• continuity_id is the stable logical session/workstream identity; every same-root active session needs a distinct continuity_id.
• session_id is temporal metadata across compaction/model switch/fork; it must not merge or split logical sessions.
• Trajectory is the route model: current functional state, desired destination/outcome, and waypoint goals.
• Trajectory, work-item, frame tags, and goals are corroborating alignment signals only; they never override project_root + continuity_id hard gates.
• Post-compaction agents should call focusa_workpoint_resume; a same-project packet resumes cleanly only when continuity_id also matches.

Context pressure UX:

• Context pressure means the transcript window is tight; it does not mean Focusa lost project memory.
• Focusa preserves continuity through scoped project identity, trajectory, Workpoint packets, evidence handles, and post-compact resume guidance.
• Generic /fork, /new, or session-handoff warnings are redundant when Focusa has healthy scoped anchors.
• Surface operator-visible warnings only when scoped Focusa anchors are unconfirmed; phrase them as checkpoint/resume guidance with /fork optional for UI isolation.

Real release behavior as of Spec89:

• Checkpoint accepted means reducer-visible active Workpoint is materialized.
• Evidence link accepted means the verification record is visible in Workpoint state/resume.
• pending means accepted by command path but not yet safe to rely on; retry current/resume.

Work-loop family

Use for continuous execution control and ownership checks.

• focusa_work_loop_writer_status — read active writer/ownership without mutation.
• focusa_work_loop_status — read loop state, budgets, replay consumer state.
• focusa_work_loop_control — on, pause, resume, stop; use preflight=true when ownership is uncertain.
• focusa_work_loop_context — update continuation decision context.
• focusa_work_loop_checkpoint — checkpoint continuous-loop state; not the same as Workpoint checkpoint.
• focusa_work_loop_select_next — defer blocked work and select next ready work item.

Writer conflicts are healthy blocked taxonomy, not generic failure. Respect active_writer.

Tree, lineage, and snapshot family

Use for recoverable ancestry and state comparison.

• focusa_tree_head — safe starting point for current branch/head context.
• focusa_tree_path — ancestry lookup for a CLT node.
• focusa_tree_snapshot_state — create recoverable checkpoint before risky work.
• focusa_tree_recent_snapshots — find snapshot IDs.
• focusa_tree_snapshot_compare_latest — create snapshot and compare against latest/baseline.
• focusa_tree_diff_context — compare snapshots.
• focusa_tree_restore_state — restore snapshot; use only when rollback is intended.
• focusa_lineage_tree — fetch lineage tree.
• focusa_li_tree_extract — extract decision/constraint/risk/reflection signals from lineage.

Snapshot before risky restore or state-changing comparisons.

Metacognition family

Use for reusable learning, not journaling.

• focusa_metacog_capture — store reusable signal; include rationale, confidence, strategy class, and evidence refs when possible.
• focusa_metacog_retrieve — retrieve prior learning before planning/reflection.
• focusa_metacog_reflect — generate hypotheses/strategy updates from recent turns.
• focusa_metacog_plan_adjust — turn reflection into tracked adjustment.
• focusa_metacog_evaluate_outcome — evaluate whether adjustment improved results.
• focusa_metacog_recent_reflections — find reflection IDs/update sets.
• focusa_metacog_recent_adjustments — find adjustment IDs.
• focusa_metacog_loop_run — compressed capture/retrieve/reflect/adjust/evaluate loop.
• focusa_metacog_doctor — diagnose signal quality/retrieval usefulness.

Respect quality_gate, evidence_refs, and suggested metrics. Improve weak signals before promotion.

State hygiene family

Use for safe cleanup planning, never silent deletion.

• focusa_state_hygiene_doctor — diagnose stale/duplicate Focus State signals without mutation.
• focusa_state_hygiene_plan — produce proposal-style hygiene plan.
• focusa_state_hygiene_apply — approval-gated, non-destructive apply that records an auditable Focus State note via /v1/focus/update.

No existing Focusa tools should be demoted; weak tools should be redesigned, clarified, merged upward, or hardened.

Trajectory, resource, and background-session utilities

• focusa_trajectory_view / focusa_trajectory_resume — advisory project goal/state/gap orientation; corroborates Workpoint, never overrides identity gates.
• focusa_trajectory_define_goal / focusa_trajectory_assess / focusa_trajectory_propose_workpoint / focusa_trajectory_checkpoint — manage project trajectory and propose next Workpoint candidates.
• focusa_resource_mode — inspect or activate LowMem when resources are constrained; LowMem changes fidelity/budgets, not tool availability.
• focusa_traverse — read-only bounded traversal across large Focusa surfaces; use instead of full tree/store/log payloads by default.
• focusa_silent_sessions — list/reopen/start/tail/send/kill tmux-backed background Pi sessions; mutating process actions require approval and kill requires force.

Tool-doctor and evidence entrypoints

• focusa_tool_doctor — first diagnostic for Focusa readiness, active Workpoint continuity, daemon health, and likely repair action; reads UIAI browser health/metrics only, never opens target URLs.
• focusa_evidence_capture — convert proof into stable handles; avoid prompt bloat.
• focusa_active_object_resolve — use before editing/claiming canonical refs when object identity is uncertain.
• focusa_browser_diagnostics_intake — after UIAI/browser diagnostics or action failure envelopes, convert browser console/network/runtime evidence into Workpoint evidence, active-object hints, prediction context, and optional metacog learning; it consumes UIAI output and does not call UIAI itself.

Browser evidence route: UIAI browser_diagnostics → focusa_browser_diagnostics_intake → focusa_active_object_resolve/prediction/evidence verification. UIAI url_not_allowed means the browser target was private/internal under hardened policy; capture it as policy evidence or use an explicit local/dev UIAI profile, not a Focusa failure. Under Focusa emergency resource mode, prefer summary trajectory/traverse views and avoid cold/full payload routes unless explicitly needed.

Commands

• /focusa-status — connection/frame/decision/constraint/failure counts.
• /focusa-stack — Focus Stack frames.
• /focusa-checkpoint — ASCC checkpoint.
• /focusa-rehydrate <handle> — retrieve externalized ECS content.
• /focusa-explain-decision [query] — search decisions.
• /focusa-lineage — CLT lineage path.
• /wbm on — Wirebot Mode.

Result-envelope contract

Every focusa_* Pi tool should preserve a visible text summary and add details.tool_result_v1 with common fields:

• ok, status, failure_class, canonical, degraded
• summary, retry, side_effects, evidence_refs, next_tools
• error, raw

Use status, failure_class, retry.posture, canonical/degraded, and next_tools for recovery decisions instead of parsing prose.

Real release evidence

Current released proof:

• docs/evidence/SPEC89_REAL_RELEASE_LIVE_PROOF_2026-04-28.md
• final live Workpoint: 019dd69d-2e7e-74a0-a722-a6ed804d040f
• proof marker: DIRECT_REAL_RELEASE_PROOF=PASS

Operator guide:

• docs/SPEC89_HARDENED_FOCUSA_TOOL_OPERATOR_GUIDE_2026-04-28.md

Maintenance checklist

After editing this skill:

1. Keep project and installed copies identical.
2. Validate Pi skill loader diagnostics are empty for Focusa.
3. Confirm /skill:focusa appears as a loaded skill in Pi’s skill set.
4. Keep description specific and under 1024 chars.
5. Keep detailed release proof in docs/evidence, not in active transcript.