How to Initialize a New Security Analysis Case in reverse‑skill: Complete Guide

Run the case-init.ps1 PowerShell script to bootstrap a standardized case folder under work/ with pre-populated scope.md, timeline.md, workitems.md, and README.md files.

The reverse‑skill repository enforces a strict case‑init workflow before any security work can begin. All analysis work must originate from a properly initialized case directory that documents authorization status, network boundaries, and next-action readiness. This process is governed by the authentication gate defined in RULES.md and automated through skills/scripts/case-init.ps1.

Prerequisites and Core Files

Before running the initialization process, ensure you have:

• PowerShell 5.1 or later
• Access to the reverse‑skill repository root
• The helper script skills/scripts/WorkRoot.ps1 available for project root resolution

The following files participate in case initialization:

File	Purpose
skills/scripts/case-init.ps1	Main bootstrap script that creates case directory and all artifacts
skills/scripts/master-route.ps1	Maps hints to primary skills and rule IDs
skills/ops/scope-contract.md	Formal contract template referenced in generated scope.md
RULES.md	Global routing rules enforcing auth-before-ACT gate
skills/scripts/smoke.ps1	CI validation for the case-init workflow

Step-by-Step Initialization Process

The case-init.ps1 script executes 12 discrete phases, each with specific validation logic:

1. Parameter Parsing (Lines 5–21)

The script accepts these key parameters:

• -Hint — Natural language description for skill routing
• -CaseName — Explicit directory name (auto-generated if omitted)
• -AuthGranted / -AuthStatus — Authorization state
• -TargetUrl / -InScopeAssets — Scope boundary definitions
• -NetworkProfile — Network operating mode
• -ReadyForAct — Override readiness calculation

2. Project Root Resolution (Lines 24–36)

Calls WorkRoot.ps1 to invoke Resolve‑ReverseProjectRoot, locating the repository root and confirming the work/ folder exists.

3. Case Directory Generation (Lines 38–53)

If -CaseName is empty, constructs a slug from the hint using pattern <date-time>-<slug>. Enforces 80-character alphanumeric limit with no trailing dots or spaces to prevent path traversal.

4. Network Profile Validation (Lines 54–57)

Accepts canonical values with automatic alias mapping:

Canonical Value	Accepted Aliases
offline	—
lab_only	lab
authorized_target_only	auth
unrestricted_lab	—

Invalid values trigger immediate termination with error.

5. Folder Tree Creation (Lines 59–65)

Creates standardized structure:

work/<case>/
├── evidence/
├── notes/
└── report/

6. Authentication Resolution (Lines 67–81)

Priority order for determining authStatusResolved:

1. Explicit -AuthStatus parameter
2. Boolean -AuthGranted flag
3. Default: pending

7. Asset List Construction (Lines 91–100)

Processes -TargetUrl and -InScopeAssets. When neither is supplied, extracts host from hint (e.g., "https://example.com" → example.com).

8. Network Mode Determination (Lines 103–119)

Default logic: authorized_target_only when auth is granted and assets exist; otherwise offline. Aliases normalized to canonical values.

9. Ready-for-ACT Calculation (Lines 125–139)

ready_for_act becomes true only when all three conditions are met:

• auth.status = granted
• At least one in-scope asset exists
• Network profile is not offline

10. Primary Skill Discovery (Lines 141–159)

Optionally invokes master-route.ps1 with the hint to auto-select:

• Primary skill path: skills/<skill>/SKILL.md
• Associated rule ID: R0, R5, etc.

11. Artifact Generation (Lines 83–103)

Renders four markdown files with UTF-8 BOM encoding:

File	Content
scope.md	Meta-information, auth block, assets, network profile, readiness flag, ops contract references
timeline.md	Initial entry: action: case-init with readiness summary
workitems.md	Starter work-item table and coverage checklist
README.md	Next-step instructions branching on readiness

12. Console Output (Lines 12–20)

Prints absolute case path, project root, selected primary skill, auth/network status, and actionable guidance.

Practical Usage Examples

Fully Authorized Target Assessment

powershell -File skills/scripts/case-init.ps1 `
    -Hint "web application pentest" `
    -CaseName "corp-portal-2024" `
    -AuthGranted `
    -TargetUrl "https://portal.example.com" `
    -NetworkProfile "authorized_target_only"

Expected output:

CASE -> C:\reverse-skill\work\corp-portal-2024
PROJECT -> C:\reverse-skill
PRIMARY skill: skills/web-pentesting/SKILL.md (R5)
auth.status=granted network_profile=authorized_target_only ready_for_act=true
NEXT: open PRIMARY SKILL.md and ACT within scope

Offline Lab Setup (Pending Authorization)

powershell -File skills/scripts/case-init.ps1 `
    -Hint "malware reverse engineering" `
    -CaseName "apt-sample-analysis"

This creates the case with ready_for_act=false, requiring manual authorization update in scope.md before proceeding.

Using Explicit Auth Status

powershell -File skills/scripts/case-init.ps1 `
    -Hint "internal network assessment" `
    -AuthStatus "granted" `
    -InScopeAssets @("192.168.0.0/24", "10.0.0.0/16") `
    -NetworkProfile "lab_only"

Security Enforcement Points

The reverse‑skill framework embeds three hard constraints:

Authorization Gate — The scope.md template contains explicit directive: - MUST NOT proceed if status != granted. The script enforces this by refusing ready_for_act unless auth.status = granted.

Network Profile Validation — Only enumerated values permitted; aliases resolved deterministically.

Case Name Hygiene — Pattern matching prevents directory traversal and illegal filesystem characters.

These constraints are validated by skills/scripts/smoke.ps1 in CI pipelines.

Generated Case Structure

A complete initialized case contains:

work/<case-name>/
├── evidence/           # Raw artifacts, memory dumps, packet captures

├── notes/              # Analyst working notes

├── report/             # Final deliverables

├── scope.md            # Master contract: auth, assets, boundaries

├── timeline.md         # Chronological case activity

├── workitems.md        # Task tracking and coverage matrix

└── README.md           # Context-aware next steps

All files use System.Text.UTF8Encoding $true for cross-platform compatibility.

Summary

• Execute case-init.ps1 to create standardized security analysis cases in reverse‑skill
• Provide -AuthGranted or -AuthStatus granted to enable ACT phase
• Specify -TargetUrl or -InScopeAssets to define scope boundaries
• Select appropriate -NetworkProfile to constrain operational environment
• Verify ready_for_act=true before beginning any active testing

The initialization process enforces the authentication-before-action principle codified in RULES.md, ensuring all case work maintains proper authorization documentation.

Frequently Asked Questions

What happens if I omit the authorization flag?

The script creates the case directory and all artifacts, but sets ready_for_act=false in scope.md and README.md. You must manually edit scope.md to update auth.status to granted before proceeding to active testing.

Can I change the network profile after initialization?

Yes. Modify scope.md directly and update the network_profile field. The script validates against canonical values, but post-init changes are permitted through manual editing with appropriate change tracking in timeline.md.

How does the script determine which primary skill to select?

When provided, the -Hint parameter is passed to master-route.ps1, which performs fuzzy matching against available skills in skills/*/SKILL.md. The matching skill path and its rule ID (e.g., R0, R5) are recorded in scope.md. If no match is found, the field remains empty for manual specification.

What encoding does reverse-skill use for generated files?

All markdown artifacts are written with UTF-8 BOM (System.Text.UTF8Encoding $true) to ensure consistent parsing across Windows, macOS, and Linux environments, particularly for non-ASCII characters in scope descriptions and evidence filenames.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}