harness-everything 0.2.1 → 0.3.6

package/docs/workflows/using-git-worktrees.md

@@ -1,63 +1,67 @@
-# Workflow: Using Git Worktrees
-
-> Manages isolated workspace environments in parallel using native Git Worktrees, enabling developers to switch contexts safely without stashing or losing unsaved progress.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `using-git-worktrees` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Switch Context Needed]) --> CheckClean["Assess if main branch has uncommitted changes"]
-  CheckClean --> CreateWorktree["Run git worktree add to a sibling directory"]
-  CreateWorktree --> CheckoutTarget["Checkout target branch or create a hotfix branch"]
-  CheckoutTarget --> OpenWorkspace["Open the sibling directory as a separate isolated workspace"]
-  OpenWorkspace --> RunDev["Perform isolated edits, tests, and debugging"]
-  RunDev --> CommitIsolated["Commit changes in the isolated workspace"]
-  CommitIsolated --> RemoveWorktree["Prune and clean up the worktree path"]
-  RemoveWorktree --> Return([Return to original workspace with pristine unsaved state intact])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `using-git-worktrees` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: worktree / isolate / checkout| WT["using-git-worktrees / SKILL.md"]
-  WT -->|Maintains isolation before running tests in| TDDSkill["tdd / SKILL.md"]
-  WT -->|Protects terminal environment testing in| EnvSkill["environment-detection / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `using-git-worktrees` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Working on deep feature 'feat-billing' (unstaged edits)"] --> Interrupt["Urgent production hotfix required!"]
-  Interrupt --> Trigger["using-git-worktrees skill invoked"]
-  Trigger --> CreateWT["Add worktree: 'git worktree add ../hotfix-auth hotfix-branch'"]
-  CreateWT --> OpenWT["Open separate workspace editor in ../hotfix-auth"]
-  OpenWT --> FixBug["Fix auth bug & run verification test"]
-  FixBug --> CommitWT["Commit fix and push branch"]
-  CommitWT --> CloseWT["Close editor, run 'git worktree prune'"]
-  CloseWT --> Resume["Return to original billing workspace with all unsaved files exactly where they were"]
-  Resume --> Done([Context switched safely with zero stashing friction])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `using-git-worktrees` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Using Git Worktrees
+
+> Manages isolated workspace environments in parallel using native Git Worktrees, enabling developers to switch contexts safely without stashing or losing unsaved progress.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `using-git-worktrees` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Trigger: Need Workspace Isolation]) --> CheckIso{1. Already in Worktree? GIT_DIR != GIT_COMMON}
+  CheckIso -->|Yes| Setup["3. Project Setup & Dependency Install"]
+  CheckIso -->|No| CheckNative{2. Native Worktree Tool Available?}
+  
+  CheckNative -->|Yes| RunNative["Use Native Worktree Tool"] --> Setup
+  CheckNative -->|No| RunGit["Try git worktree add .worktrees/branch"]
+  
+  RunGit -->|Success| Setup
+  RunGit -->|Fails / Sandbox Denied| WorkInPlace["Fallback: Work in Place in Current Directory"] --> Setup
+  
+  Setup --> RunBaseline["4. Verify Clean Test Baseline"]
+  RunBaseline --> End([Isolated Workspace Ready])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `using-git-worktrees` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: worktree / isolate / checkout| WT["using-git-worktrees / SKILL.md"]
+  WT -->|Maintains isolation before running tests in| TDDSkill["tdd / SKILL.md"]
+  WT -->|Protects terminal environment testing in| EnvSkill["environment-detection / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `using-git-worktrees` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Working on deep feature 'feat-billing' (unstaged edits)"] --> Interrupt["Urgent production hotfix required!"]
+  Interrupt --> Trigger["using-git-worktrees skill invoked"]
+  Trigger --> CreateWT["Add worktree: 'git worktree add ../hotfix-auth hotfix-branch'"]
+  CreateWT --> OpenWT["Open separate workspace editor in ../hotfix-auth"]
+  OpenWT --> FixBug["Fix auth bug & run verification test"]
+  FixBug --> CommitWT["Commit fix and push branch"]
+  CommitWT --> CloseWT["Close editor, run 'git worktree prune'"]
+  CloseWT --> Resume["Return to original billing workspace with all unsaved files exactly where they were"]
+  Resume --> Done([Context switched safely with zero stashing friction])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `using-git-worktrees` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/verification-loop.md

@@ -1,69 +1,71 @@
-# Workflow: Verification Loop
-
-> Comprehensive pre-PR quality gate executing builds, linting, type-checking, test suites, and security scans before claiming a task complete.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `verification-loop` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Pre-PR Quality Check Triggered]) --> RunBuild["Execute compilation / project build"]
-  RunBuild --> CheckBuild{Build succeeded?}
-  CheckBuild -->|No| FixBuild["Debug and fix build errors"]
-  CheckBuild -->|Yes| RunTypeCheck["Execute language type-checking compiler"]
-  RunTypeCheck --> CheckTypes{Typecheck green?}
-  CheckTypes -->|No| FixTypes["Correct type-definition errors"]
-  CheckTypes -->|Yes| RunLint["Execute code linter checks"]
-  RunLint --> CheckLint{Lint clean?}
-  CheckLint -->|No| FixLint["Correct code-style and syntax errors"]
-  CheckLint -->|Yes| RunTests["Execute complete automated test suite"]
-  RunTests --> CheckTests{Tests passed?}
-  CheckTests -->|No| FixTests["Debug and correct failing tests"]
-  CheckTests -->|Yes| End([Pre-PR verification gate cleared successfully])
-  FixBuild & FixTypes & FixLint & FixTests --> RunBuild
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `verification-loop` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Pre-PR checks / gate| VerLoop["verification-loop / SKILL.md"]
-  VerLoop -->|Guards finalize step in| Todo["todo-driven-workflow / SKILL.md"]
-  VerLoop -->|Requires test environment setup from| Env["environment-detection / SKILL.md"]
-  VerLoop -->|Precedes safe commit push in| GitCommit["git-commit / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `verification-loop` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Feature code written; ready to claim task complete"] --> Trigger["verification-loop skill runs"]
-  Trigger --> Build["Run 'npm run build' -> Succeeded"]
-  Build --> Type["Run 'npm run typecheck' -> Found 2 type mismatches in routes.ts"]
-  Type --> FixT["Fix incorrect type casting in routes.ts"]
-  FixT --> Recheck["Re-run typecheck -> Succeeded"]
-  Recheck --> Lint["Run 'npm run lint' -> Clean"]
-  Lint --> Tests["Run 'npm run test' -> 24 tests passed"]
-  Tests --> Done([Verification loop complete; safe to open PR])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `verification-loop` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Verification Loop
+
+> Comprehensive pre-PR quality gate executing builds, linting, type-checking, test suites, and security scans before claiming a task complete.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `verification-loop` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Pre-PR Quality Check Triggered]) --> RunBuild["1. Phase 1: Build Verification"]
+  RunBuild --> RunTypeCheck["2. Phase 2: Type Check (tsc / pyright)"]
+  RunTypeCheck --> RunLint["3. Phase 3: Lint Check"]
+  RunLint --> RunTests["4. Phase 4: Test Suite Execution"]
+  RunTests --> RunSecurity["5. Phase 5: Security & Secret Scan"]
+  RunSecurity --> DiffReview["6. Phase 6: Diff Review"]
+  
+  DiffReview --> CheckScript{7. Is verify-gate.js / Template Available?}
+  CheckScript -->|Yes| ScriptReport["Run harness-everything/scripts/verify-gate.js & Fill Template"]
+  CheckScript -->|No| DirectReport["Output Verification Report Inline"]
+  
+  ScriptReport --> CheckGate{All Verification Gates Passed?}
+  DirectReport --> CheckGate
+  
+  CheckGate -->|No| FixIssues["Fix Issues in Code & Re-verify"] --> RunBuild
+  CheckGate -->|Yes| End([Pre-PR Verification Gate Cleared])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `verification-loop` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Pre-PR checks / gate| VerLoop["verification-loop / SKILL.md"]
+  VerLoop -->|Guards finalize step in| Todo["todo-driven-workflow / SKILL.md"]
+  VerLoop -->|Requires test environment setup from| Env["environment-detection / SKILL.md"]
+  VerLoop -->|Precedes safe commit push in| GitCommit["git-commit / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `verification-loop` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Feature code written; ready to claim task complete"] --> Trigger["verification-loop skill runs"]
+  Trigger --> Build["Run 'npm run build' -> Succeeded"]
+  Build --> Type["Run 'npm run typecheck' -> Found 2 type mismatches in routes.ts"]
+  Type --> FixT["Fix incorrect type casting in routes.ts"]
+  FixT --> Recheck["Re-run typecheck -> Succeeded"]
+  Recheck --> Lint["Run 'npm run lint' -> Clean"]
+  Lint --> Tests["Run 'npm run test' -> 24 tests passed"]
+  Tests --> Done([Verification loop complete; safe to open PR])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `verification-loop` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/verify-before-claim.md

@@ -1,60 +1,64 @@
-# Workflow: Verify Before Claim
-
-> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Claim or Estimate Proposed]) --> IdentifyAssumptions["Isolate any claim or performance assumption"]
-  IdentifyAssumptions --> QueryAuthoritative["Execute WebSearch or read local code sources"]
-  QueryAuthoritative --> CrossVerify["Cross-verify details with authoritative documentation"]
-  CrossVerify --> RunLocalExperiment["Run quick script to empirically test the assumption"]
-  RunLocalExperiment --> CaptureResult["Log actual measured results and exit-codes"]
-  CaptureResult --> AssertFact["Assert verified fact based on objective data"]
-  AssertFact --> End([Hypothesis replaced with empirical truth])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `verify-before-claim` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
-  VBC -->|Empirical verification helper| RunCode["mcp_provides_tool_pylanceRunCodeSnippet / run_in_terminal"]
-  VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
-  VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
-  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
-  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
-  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
-  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
-  UpdateCode --> Done([Potential production runtime crash prevented])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `verify-before-claim` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Verify Before Claim
+
+> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([About to Assert External Framework / API Behavior or Perf Number]) --> CheckScope{Claim Scope Check}
+  CheckScope -->|Internal Repo Code| ReadSource["Read Local Source Code -> State Facts"]
+  CheckScope -->|External Framework / API / Number| CheckNet{Web Fetch / Search / Measurement Available?}
+  
+  CheckNet -->|Yes| FetchDocs["WebFetch Official Docs / Measure Real Execution"]
+  CheckNet -->|No / Offline| EstimateFallback["Explicitly Label Response as Unverified Estimate"]
+  
+  FetchDocs --> CiteDocs["Quote Authoritative Source / State Measured Data"]
+  ReadSource --> End([Verified Output Delivered])
+  CiteDocs --> End
+  EstimateFallback --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `verify-before-claim` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
+  VBC -->|Empirical verification helper| RunCode["Run a real Node/terminal measurement"]
+  VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
+  VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
+  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
+  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
+  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
+  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
+  UpdateCode --> Done([Potential production runtime crash prevented])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `verify-before-claim` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/zoom-out.md

@@ -1,62 +1,74 @@
-# Workflow: Zoom Out
-
-> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([3 Consecutive Errors Triggered]) --> Tripped{Rule of 3 Tripped?}
-  Tripped -->|No| Backtrack["Review code change and retry"]
-  Tripped -->|Yes| LockWork["Lock all file edit capabilities"]
-  LockWork --> GatherState["Analyze current working directory, file states, and errors"]
-  GatherState --> GenReport["Compile formal Reflection Report: what failed, assumptions, backtracking options"]
-  GenReport --> PresentReport["Present report to human partner and request guidance"]
-  PresentReport --> End([Workforce unlocked after human direction received])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `zoom-out` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
-  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
-  ZoomOut -->|Asks for human direction via| AskQuestions["vscode_askQuestions"]
-  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
-  Trigger --> Lock["Workspace writes locked"]
-  Trigger --> Collect["Collect error traces and diff history"]
-  Collect --> WriteReport["Create docs/reflection/zoom-out-report.md detailing the import cyclic dependency"]
-  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
-  Present --> UserChoice["User select: 'Option B'"]
-  UserChoice --> Unlock["Unlock workspace and execute Option B"]
-  Unlock --> Done([Error loop successfully broken and resolved])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `zoom-out` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Zoom Out
+
+> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([3 Consecutive Failures / Goal Drift Triggered]) --> CeaseFire["1. Phase 1: Cease Fire - Stop Code Edits Immediately"]
+  CeaseFire --> Rebuild["2. Phase 2: Rebuild Full Picture using Read-Only Tools"]
+  Rebuild --> CheckPath{3. Resolve Reflection Report Path}
+  
+  CheckPath -->|Session Path Provided| WriteSession["Copy template to Session zoom-out-report.md"]
+  CheckPath -->|Template / Path Unavailable| WritePlatform["Write to .github/harness-everything/zoom-out-report.md or Inline"]
+  
+  WriteSession --> DecisionGate{4. Phase 4: Decision Gate}
+  WritePlatform --> DecisionGate
+  
+  DecisionGate -->|Untried Path Identified| Resume["RESUME: Execute Fresh Diagnosis in TDD / Fable"]
+  DecisionGate -->|Requirement Conflict / Access Gap| Escalate["ESCALATE: Present 2-3 Options + Recommendation to Human"]
+  
+  Resume --> Resolved{5. Problem Cracking Succeeds?}
+  Resolved -->|Yes| SelfEvolve["Call self-evolve to Persist Insight"]
+  Resolved -->|No: 3 More Failures| Escalate
+  SelfEvolve --> End([Reflection Completed & Lessons Persisted])
+  Escalate --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `zoom-out` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
+  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
+  ZoomOut -->|Asks for human direction via| AskQuestions["host user-input mechanism"]
+  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
+  Trigger --> Lock["Workspace writes locked"]
+  Trigger --> Awaken["Awaken: Stop error-fixing; review imports design & requirements (Law 2)"]
+  Awaken --> Collect["Collect error traces and diff history"]
+  Collect --> WriteReport["Create the session zoom-out-report.md detailing the import cyclic dependency"]
+  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
+  Present --> UserChoice["User select: 'Option B'"]
+  UserChoice --> Unlock["Unlock workspace and execute Option B"]
+  Unlock --> Done([Error loop successfully broken and resolved])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `zoom-out` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.