# How to Document Findings with the Timeline and Field-Journal System in Reverse-Skill

> Learn how to document findings using the Timeline and Field-Journal system in the reverse-skill repository. Capture actions, create evidence chains, and enhance routing capabilities.

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

---

**The reverse-skill repository implements an immutable timeline and anonymized field-journal workflow that captures every investigative action, creates traceable evidence chains, and automatically evolves the system's routing capabilities.**

The `zhaoxuya520/reverse-skill` repository provides a structured documentation framework designed for security and reverse-engineering investigations. When analysts document findings with the timeline and field-journal system, they create a reproducible audit trail that preserves operational knowledge while protecting sensitive data. This workflow ensures that every command, result, and lesson learned feeds back into the system's evolution through automatic router and tool manifest updates.

## Understanding the Timeline and Field-Journal Workflow

According to the architecture defined in [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md), the system executes a specific sequence when processing tasks. The AI first reads the global rules from [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the skill entry point at [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md), and the routing matrix at [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md). Before executing the selected skill, the system checks the **field-journal** for prior experience and consults the **tool-index** for available utilities.

After skill execution completes, the framework automatically generates a new journal entry and updates the master index. This creates a closed loop where documentation directly improves future routing decisions, a process referred to as "auto-evolution" in the source architecture.

## Creating Immutable Timeline Entries

Each investigation case maintains a dedicated timeline file at `work/<case>/timeline.md` that records a chronological series of immutable blocks. These entries provide a replay-able audit trail suitable for diff-review and compliance verification.

### Timeline Block Format

As specified in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), every timeline entry follows a strict markdown structure:

```markdown

## {ISO-8601} | {role} | {phase}

- action:
- command_or_ref:
- result_summary:
- artifacts: []      # relative paths under this case

- evidence_ids: []   # E-xxx when promoted

- next:

```

The header combines an ISO-8601 timestamp, the analyst's role, and the current investigation phase. The key-value pairs track the specific action taken, the command or reference used, a summary of results, associated artifact paths, evidence identifiers, and the next planned step.

### Appending vs. Modifying Entries

**Existing blocks must never be altered.** To maintain forensic integrity, the system enforces an append-only policy. When corrections are necessary, analysts create new blocks that reference the original using the `corrects:` field. This immutability guarantee ensures that the complete history of an investigation remains transparent and auditable.

## Capturing Knowledge in the Field-Journal

The **field-journal** serves as the repository's long-term memory, storing anonymized experience after tasks complete. Located under `skills/field-journal/`, these files enable knowledge reuse across investigations while ensuring operational security.

### Anonymization Requirements

Before committing any journal entry, analysts must execute the anonymization checklist defined in [`skills/field-journal/anonymization.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/anonymization.md). All sensitive data—including IP addresses, tokens, and hostnames—must be replaced with standardized placeholders such as `{target_ip}` or `{token}`. This scrubbing process ensures that operational details remain confidential while the methodological knowledge becomes reusable.

### Journal Entry Structure

The template at [`skills/field-journal/_template.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/_template.md) defines seven required sections:

- **Scope** – Investigation boundaries and objectives
- **Evidence Chain** – Links to timeline entries and raw artifacts
- **Findings** – Key discoveries and vulnerabilities
- **Pitfalls** – Failed approaches and dead ends
- **Tool Observations** – Performance notes and compatibility issues
- **Reusable Snippets** – Command templates and automation scripts
- **Evolution Actions** – Suggested improvements to routing or tools

Completed journals follow the naming convention `YYYY-MM-DD_*.md` and are automatically indexed in [`field-journal/_index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/field-journal/_index.md) for instant discovery.

## Integrating Timeline, Evidence, and Work Items

The documentation system creates traceable chains through three interconnected components. **WorkItem tracking** (`work/<case>/workitems.md`) maps each timeline entry to specific coverage checkpoints such as "Recon complete" or "Report exported." **Evidence linkage** connects timeline entries to raw artifacts stored under `work/<case>/evidence/` via the `evidence_ids` field, creating an unbroken chain from command execution to final findings.

This integration enables comprehensive coverage checks and ensures that no investigative step occurs without corresponding documentation.

## Automating Documentation with PowerShell and Bash

The repository includes automation scripts that streamline documentation creation while enforcing format compliance.

### Initializing Case Timelines

The `skills/scripts/case-init.ps1` script demonstrates how to bootstrap a new investigation with a properly formatted timeline entry:

```powershell

# Assume $case = "acme-2026", $role = "lead", $phase = "recon"

$timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"
$entry = @"

## $timestamp | $role | $phase

- action: Discover open ports
- command_or_ref: nmap -sS $target_ip
- result_summary: Found 22/tcp, 80/tcp, 443/tcp
- artifacts: [work/$case/evidence/nmap_$timestamp.txt]
- evidence_ids: [E-001]
- next: Perform service enumeration
"@

Add-Content -Path "work/$case/timeline.md" -Value $entry

```

### Generating Field-Journal Entries

Analysts can generate new journal files from the template using parameter substitution:

```powershell
$today = Get-Date -Format "yyyy-MM-dd"
$journal = Get-Content "skills/field-journal/_template.md"
$journal = $journal -replace "\[日期\] \[项目简称\]", "$today Acme PenTest"
$journal = $journal -replace "\[项目简称\]", "Acme"

# Fill in sections as needed …

$journalPath = "skills/field-journal/${today}_acme_pentest.md"
$journal | Set-Content $journalPath

# Run anonymization checker (script defined in field-journal/scripts)

.\skills\field-journal\scripts\scan-leaks.ps1 -File $journalPath

```

### Updating the Master Index

After creating a journal entry, the following bash script updates the categorical index:

```bash
#!/usr/bin/env bash
INDEX="skills/field-journal/_index.md"
NEW_ENTRY=$(basename "$1")

# Insert a line under the appropriate category (e.g., "Pentest")

sed -i "/## Pentest/a\\

- $NEW_ENTRY" "$INDEX"

```

## Enabling Auto-Evolution Through Documentation

The timeline and field-journal system directly drives the repository's self-improvement capabilities. After the journal is written and anonymization verified, the system automatically refreshes [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md), and the bootstrap manifest when new tools or routing paths are detected. This ensures that successful methodologies captured in today’s investigation become available routing options for tomorrow's tasks.

## Summary

- **Immutable timelines** at `work/<case>/timeline.md` provide append-only audit trails using ISO-8601 timestamps and structured key-value blocks.
- **Anonymized field-journals** follow the template in [`skills/field-journal/_template.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/_template.md) and require placeholder substitution for all sensitive data before storage.
- **Evidence integration** links timeline entries to work items and raw artifacts, creating comprehensive traceability from command to conclusion.
- **Automated updates** to routing matrices and tool indices occur after journal submission, enabling continuous system evolution based on documented findings.
- **Format compliance** is enforced through PowerShell initialization scripts and bash index management tools located in `skills/scripts/` and `skills/field-journal/scripts/`.

## Frequently Asked Questions

### How does the timeline ensure data integrity?

The timeline enforces an append-only policy where existing blocks must never be modified. Corrections are added as new entries using the `corrects:` field to reference the original block. This immutability guarantee, defined in [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md), creates a replay-able audit trail suitable for diff-review and compliance verification.

### What sensitive information must be anonymized in field-journal entries?

All case-specific sensitive data including IP addresses, authentication tokens, hostnames, and usernames must be replaced with placeholders like `{target_ip}` or `{token}`. The anonymization checklist in [`skills/field-journal/anonymization.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/anonymization.md) specifies these requirements to ensure operational security while preserving methodological value.

### How does the system route new tasks based on previous journals?

When a new task begins, the AI checks [`field-journal/_index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/field-journal/_index.md) and relevant journal entries for prior experience related to the current investigation type. According to [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md), this historical knowledge informs the routing decision through [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), allowing the system to select optimal tools and approaches based on documented past performance.

### Can timeline entries be modified after creation?

No, timeline entries cannot be modified once written. The system treats `work/<case>/timeline.md` as an immutable ledger. If an error is discovered, analysts must append a new block that references the incorrect entry via the `corrects:` field, preserving the complete investigative history while acknowledging the revision.