# Understanding reverse-skill's Ops Contracts: Scope-Contract, Evidence-Finding-Path, and Role-Map

> Learn about reverse-skill's Ops Contracts scope-contract, evidence-finding-path, and role-map for authorization, documentation, and role clarity in security engagements. Improve your workflow now.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-05

---

**reverse-skill uses three plain Markdown contracts—scope-contract, evidence-finding-path, and role-map—to enforce authorization, structured documentation, and clear role responsibilities across every security engagement.**

This guide explains how to implement reverse-skill's ops contracts based on the source files in `zhaoxuya520/reverse-skill`. These contracts replace ad-hoc tracking with lightweight, version-controlled Markdown that requires no database or external ticketing system.

---

## What Are reverse-skill's Ops Contracts?

The `skills/ops/` directory contains three complementary contracts that govern every phase of a reverse-engineering, pentest, or security engagement:

| Contract | File Location | Purpose |
|----------|-------------|---------|
| **Scope-contract** | [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) | Authorization gate before any active operation |
| **Evidence-finding-path** | [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) | Three-layer evidence chain (raw → analyzed → narrative) |
| **Role-map** | [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) | Role-to-skill mapping and hand-off protocols |

All contracts use human-readable Markdown with machine-parseable keys, enabling both manual editing and PowerShell automation.

---

## Scope-Contract: The Authorization Gate

The scope-contract in [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) mandates that **no active "ACT" step can occur without a valid [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file**. This hard gate prevents unauthorized operations by enforcing explicit documentation of assets, constraints, and sign-offs.

### Required Sections in [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md)

Every case scope must include:

- **`meta`** – case ID, operator, primary skill, lead role, specialist roles
- **`auth`** – authorization status (`granted` required), basis, evidence reference
- **`in_scope`** – assets, surfaces, allowed activities
- **`out_of_scope`** – explicitly excluded targets and actions
- **`network_profile`** – connectivity mode: `offline`, `lab_only`, `authorized_target_only`, or `unrestricted_lab`
- **`constraints`** – timebox, stealth level, data handling rules
- **`deliverables`** – required artifacts (report, field journal, diagrams, timeline)
- **`signoff`** – checklist that must pass before proceeding

### Creating a Scope-Contract with PowerShell

Use the `case-init.ps1` helper to bootstrap a new case:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\case-init.ps1 `
  -Hint "Enumerate vulnerable IoT devices" -CaseName "iot-audit"

```

This creates [`work/iot-audit/scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/iot-audit/scope.md) pre-filled with the template structure.

### Validating Scope Before Action

The contract enforces that `auth.status` must equal `granted` and `network_profile.mode` must match the operational environment. A minimal valid scope looks like:

```markdown

## auth

- status: granted
- basis: bug_bounty_scope
- evidence_of_auth: ticket/12345

## network_profile

- mode: authorized_target_only
- notes: Only enumerated targets may be contacted

## signoff

- ready_for_act: true
- checklist:
  - [x] auth.status = granted
  - [x] in_scope.assets non-empty
  - [x] network_profile.mode chosen
  - [x] out_of_scope reviewed

```

---

## Evidence-Finding-Path: Structured Documentation Chain

The evidence-finding-path contract in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) defines a **three-layer hierarchy** connecting raw observations to validated findings and complete attack or solve narratives.

### The Three Layers

| Layer | ID Pattern | Mandatory Fields | Purpose |
|-------|-----------|------------------|---------|
| **Evidence** | `E-001` | `title`, `observed_at`, `source_type`, `source_ref`, `content_hash`, `repro_command`, `raw_excerpt`, `linked_workitem`, `supersedes` | Immutable raw observation |
| **Finding** | `F-001` | `title`, `severity`, `category`, `status`, `evidence_ids`, `location`, `impact`, `confidence`, `repro_steps`, `remediation` | Analyst conclusion with evidence backing |
| **Path** | `P-001` | `title`, `path_type`, `start`, `goal`, `steps`, `residual_risks` | End-to-end narrative linking steps to evidence and findings |

### Recording Evidence with CLI Helpers

The `append-evidence.ps1` script creates properly formatted evidence files:

```powershell
powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/iot-audit `
  -Id E-001 -Title "Nmap open ports" -ReproCommand "nmap -sV 192.168.1.10" `
  -Severity info -Status observed

```

This generates [`work/iot-audit/evidence/E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/iot-audit/evidence/E-001.md) with all required fields pre-populated.

### Creating Findings and Paths Manually

Findings reference evidence IDs and add analysis:

```markdown

### F-001

- title: Exposed Telnet service with default credentials
- severity: critical
- category: vuln
- status: validated
- evidence_ids: [E-001, E-002]
- location: 192.168.1.10:23
- confidence: high
- repro_steps:
  1. telnet 192.168.1.10
  2. Login with admin/admin
- remediation: Disable Telnet; enforce SSH with key auth

```

Paths connect findings into operational narratives:

```markdown

### P-001

- title: IoT device compromise via Telnet
- path_type: attack
- start: Network access to target segment
- goal: Root shell on IoT gateway
- steps:
  1. action: Discover Telnet service — evidence: E-001 — finding: F-001
  2. action: Enumerate connected devices — evidence: E-003 — finding: F-002
  3. action: Exploit UART debug interface — evidence: E-010 — finding: F-005
- residual_risks: Physical access required for step 3

```

### Enforcement Rules in evidence-finding-path

- Every Finding **must** reference at least one Evidence (`evidence_ids` non-empty)
- Validated Findings cannot have `confidence: low` without noted residual risk
- Paths must reference Evidence for each step; final Finding must be validated before success claim

---

## Role-Map: Responsibility and Hand-Off Management

The role-map contract in [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) defines **who operates on which skills** and how responsibilities transition during an engagement. It operates independently of any orchestration engine—all data stays in Markdown.

### Core Role Codes

| Code | Full Name | Primary Skills |
|------|-----------|---------------|
| `lead` | Engagement Lead | Scope writing, role assignment, timeline management |
| `cie` | Intelligence & Enumeration Specialist | Recon, OSINT, asset discovery |
| `cpe` | Exploitation & Post-Exploitation Specialist | Vulnerability validation, privilege escalation |
| `cre` | Reverse Engineering Specialist | Binary analysis, firmware extraction |
| `doc` | Documentation & Reporting Specialist | Report generation, diagram creation |

### Lead Protocol Requirements

The lead role **must**:

1. Write or approve the [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file
2. Assign specialist roles in `meta.specialist_roles`
3. Manage all hand-off transitions
4. Maintain [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) with role-prefixed entries

### Hand-Off Matrix and Triggers

Role transitions require specific triggers and deliverables:

| From | To | Trigger | Required Deliverable |
|------|-----|---------|----------------------|
| `lead` | `cie` | Scope approved, authorization granted | Completed [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) with `ready_for_act: true` |
| `cie` | `cpe` | Live service or vulnerability discovered | Asset list with evidence references |
| `cpe` | `cre` | Binary or firmware obtained for analysis | Sample file with extraction notes |
| `any` | `doc` | Evidence/Finding draft complete | Structured markdown ready for report |

### Single-Agent Usage

When one analyst performs multiple roles, prefix all timeline entries with role tags:

```markdown

# timeline.md

[lead] 2024-01-15 09:00 – Scope created, auth granted for target.example.com
[cie] 2024-01-15 10:30 – Open ports discovered on 203.0.113.5
[cie] → [cpe] 2024-01-15 10:35 – Handoff: SSH service identified, begin exploitation
[cpe] 2024-01-15 11:00 – Validated weak key authentication (E-005 → F-003)
[cpe] → [doc] 2024-01-15 12:00 – Path P-001 complete, draft findings ready

```

---

## Complete Workflow Example

This example demonstrates all three reverse-skill ops contracts in sequence:

### 1. Initialize Case (Scope-Contract)

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\case-init.ps1 `
  -Hint "Audit Windows AD environment" -CaseName "ad-audit"

```

Edit [`work/ad-audit/scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/ad-audit/scope.md):

```markdown

## meta

- case_id: 20240115-01
- operator: analyst1
- primary_skill: windows-ad
- lead_role: lead
- specialist_roles: [cie, cpe]

## auth

- status: granted
- basis: internal_audit
- evidence_of_auth: email/audit-approval-2024q1

## in_scope

- assets: [10.10.10.5]
- surfaces: [ldap, kerberos, smb]
- activities: [recon, exploit_validate, post_exploit]

## network_profile

- mode: authorized_target_only

## constraints

- timebox: 40 hours
- stealth: low_interaction

## signoff

- ready_for_act: true
- checklist:
  - [x] auth.status = granted
  - [x] in_scope.assets non-empty
  - [x] network_profile.mode chosen

```

### 2. Record Evidence (Evidence-Finding-Path)

```powershell
powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/ad-audit `
  -Id E-001 -Title "Anonymous LDAP bind successful" `
  -ReproCommand "ldapsearch -x -h 10.10.10.5 -s base namingcontexts" `
  -Severity info -Status observed

```

### 3. Create Finding

```markdown
<!-- work/ad-audit/finding/F-001.md -->

### F-001

- title: LDAP server allows anonymous bind
- severity: medium
- category: config_weakness
- status: validated
- evidence_ids: [E-001]
- location: 10.10.10.5:389
- confidence: high
- repro_steps:
  1. Execute ldapsearch with -x flag
  2. Observe successful connection without credentials
- remediation: Disable anonymous bind in slapd.conf

```

### 4. Build Attack Path

```markdown
<!-- work/ad-audit/path/P-001.md -->

### P-001

- title: Domain enumeration via anonymous LDAP
- path_type: attack
- start: Network connectivity to domain controller
- goal: Complete domain user list
- steps:
  1. action: Confirm anonymous bind — evidence: E-001 — finding: F-001
  2. action: Extract user list with filter (objectClass=user) — evidence: E-010 — finding: F-005
  3. action: Identify password policy — evidence: E-011 — finding: F-006
- residual_risks: Account lockout possible if interaction limits exceeded

```

### 5. Document Role Transitions (Role-Map)

```markdown
<!-- work/ad-audit/timeline.md -->
[lead] 2024-01-15 09:00 – Scope approved, specialist roles assigned.
[cie] 2024-01-15 10:00 – LDAP port discovered on 10.10.10.5:389.
[cie] → [cpe] 2024-01-15 10:15 – Handoff: authentication service identified.
[cpe] 2024-01-15 11:00 – Anonymous bind validated, E-001 created.
[cpe] 2024-01-15 11:30 – Domain enumeration complete, F-005/F-006 created.
[cpe] → [doc] 2024-01-15 12:00 – Path P-001 finalized for reporting.

```

---

## Summary

- **Scope-contract** ([`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md)) is the mandatory authorization gate—no active operations without `auth.status: granted` and completed sign-off checklist
- **Evidence-finding-path** ([`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)) enforces a three-layer documentation hierarchy: immutable Evidence → validated Finding → narrative Path
- **Role-map** ([`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)) defines role-to-skill assignments, lead protocols, and hand-off triggers with required deliverables
- All contracts use **plain Markdown** with parseable keys, enabling both manual editing and PowerShell automation via `case-init.ps1` and `append-evidence.ps1`
- The framework is **tool-agnostic**—no external APIs, databases, or ticketing systems required

---

## Frequently Asked Questions

### What happens if I try to run an active operation without a scope-contract?

According to the [`scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope-contract.md) source, **no ACT step is permitted** without a valid [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file showing `auth.status: granted`. The contract explicitly states "No scope → only documentation/routing allowed." Attempting reconnaissance, exploitation, or reverse engineering without authorization triggers a protocol violation.

### How does evidence-finding-path ensure findings are reproducible?

The contract mandates that every Evidence include `repro_command`, `source_ref`, and `content_hash` fields. Every Finding must reference at least one Evidence via `evidence_ids` and include `repro_steps`. This creates an auditable chain from raw observation to analyst conclusion, with the Path layer providing narrative context for complex operations.

### Can I use reverse-skill's ops contracts without the PowerShell helpers?

Yes. The contracts are **pure Markdown** with no dependency on `case-init.ps1` or `append-evidence.ps1`. You can manually create `work/<case>/scope.md`, `evidence/E-*.md`, `finding/F-*.md`, and other files following the templates in `skills/ops/`. The PowerShell scripts are convenience wrappers that enforce field presence and consistent formatting.

### How do role-map hand-offs work when multiple analysts collaborate?

The lead role manages transitions via the hand-off matrix documented in [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md). Each transition requires a **trigger condition** (e.g., "live service discovered") and a **deliverable** (e.g., asset list with evidence references). The transfer is recorded in [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) with role prefixes (`[cie] → [cpe]`), creating an audit trail of responsibility changes.