sop

name	sop
version	1.1.0
description	Standard Operating Procedure — phase-based execution with sequential step checklists and structured working files. (Mandatory execution methodology, follow SKILL.md to setup before any other tool calls)

SOP Skill

Execute structured tasks by following predefined phases with step-by-step checklists. Unlike exploratory research (scientific method), SOP tasks have known procedures — the focus is on thorough execution, not hypothesis testing.

Files

File	Purpose	When to Update
plan.md	Phases, steps, decisions, current state	After each step/phase
findings.md	Discoveries, technical decisions, issues	After ANY discovery
progress.md	Execution log, errors, test results	Throughout execution

Responsibility Split

• plan.md = How you execute — phase/step structure, checklist, decisions
• findings.md = What you found — research results, technical decisions, issues encountered
• progress.md = What you did — action log per phase, errors, test results

Quick Start

1. Copy templates FIRST — this is your FIRST action. No other tool calls are allowed before these files exist. Do NOT create these files from scratch. The templates contain required structure and comments. If the files already exist, skip this step.

   cp <SKILL_DIR>/templates/plan.md .
   cp <SKILL_DIR>/templates/findings.md .
   cp <SKILL_DIR>/templates/progress.md .
   

   <SKILL_DIR> is the directory containing this SKILL.md. Resolve from your runtime context.

2. Understand your task — read the assignment/brief to identify the phases
3. Fill in Goal + Phases in plan.md. Update Current State **Phase:** and **Step:** to your starting position.
4. Execute phases in order — check off steps as you go
5. Update findings.md after every 2 search/browse/view operations (2-Action Rule)
6. Update progress.md with actions taken at each phase gate

Core Rules

1. Plan First

Copy the templates. Fill in the phases from your task brief. Do not start execution without plan.md.

2. Execute in Order

Phases are sequential. Do not skip ahead. Each phase must be completed before moving to the next, unless explicitly marked [skipped] reason.

3. The 2-Action Rule

After every 2 search/browse/view operations, IMMEDIATELY save key findings to findings.md.

Visual and browser content is lost if not written to disk promptly.

4. Phase Gate

Before starting the next phase, complete ALL of these:

1. Check off completed steps in plan.md
2. Update phase status: in_progress → complete
3. Update Current Phase to the next phase
4. Save any new discoveries to findings.md
5. Log actions taken in progress.md for the current phase
6. Verify: re-read progress.md and confirm the phase section is filled in

5. Read Before Decide

Before major decisions, re-read plan.md. This refreshes goals in your attention window.

6. Log ALL Errors

Every error goes in progress.md Errors table. Track what you tried. Never repeat the exact same failing action.

7. The 3-Strike Protocol

Attempt 1: Diagnose & fix — read error, identify root cause, apply targeted fix
Attempt 2: Alternative approach — different method, different tool
Attempt 3: Broader rethink — question assumptions, search for solutions
After 3 failures: Log in findings.md Issues Encountered — document what you tried and the blockers

The 5-Question Reboot Test

If you can answer these from your files, your context is solid:

Question	Source
Where am I?	Current Phase + Step in plan.md
Where am I going?	Remaining phases
What's the goal?	Goal in plan.md
What have I found?	findings.md
What have I done?	progress.md

Critical Rules

When a Hook Denies Your Action

Hooks are lightweight sentries that enforce working-file discipline. When a hook denies your action:

1. Read the deny message carefully — it tells you exactly what is wrong
2. Fix the issue in your working files — update the files the message identifies
3. Refer to <SKILL_DIR>/templates/ for correct file structure if unsure what goes where
4. Retry your original action — it will succeed once the issue is resolved

Do NOT attempt to bypass hooks, reset file timestamps, or modify hook-managed files to work around a denial.

Hook-Managed Files

The following files are managed by hooks and must never be manually created, modified, or deleted:

• .context_refresh_ts — timestamp file used by the context-refresh hook to track refresh intervals

Preserve Template Structure

The plan.md template structure is enforced by hooks. Do not rename, remove, or merge these required elements:

• Phase sections: ### Phase N: with **Status:**, **Prerequisites:**, and at least one checklist item (- [ ] or - [x])
• Status fields: Every phase that has a **Status:** field must keep it. Valid values: not_started, in_progress, complete
• Required top-level section: ## Phases
• Current State format: **Phase:** and **Step:** must be non-empty

Keep Files Fresh

Working files must be updated at least every 2 minutes, regardless of the 2-Action Rule. Stale files trigger a staleness denial.

• Before long operations (builds, tests, large searches): update progress.md with what you are about to do
• After completing work: update findings.md with what you discovered

The staleness hook checks modification timestamps on plan.md, progress.md, and findings.md. Writing real content resets the clock. Do NOT touch or reset file timestamps — write actual progress.