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

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, the system executes a specific sequence when processing tasks. The AI first reads the global rules from RULES.md, the skill entry point at skills/SKILL.md, and the routing matrix at 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, every timeline entry follows a strict markdown structure:

## {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. 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 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 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:

# 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:

$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:

#!/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, 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 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, 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 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 and relevant journal entries for prior experience related to the current investigation type. According to docs/ARCHITECTURE.md, this historical knowledge informs the routing decision through 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.

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