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

> Initialize a new security analysis case in reverse-skill by running case-init.ps1. This guide shows you how to quickly set up your analysis environment with essential files.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Run the `case-init.ps1` PowerShell script to bootstrap a standardized case folder under `work/` with pre-populated [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md), and [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) | Formal contract template referenced in generated [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) | Meta-information, auth block, assets, network profile, readiness flag, ops contract references |
| [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md) | Initial entry: `action: case-init` with readiness summary |
| [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/workitems.md) | Starter work-item table and coverage checklist |
| [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) before proceeding.

### Using Explicit Auth Status

```powershell
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) and [`README.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md). You must manually edit [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.