skill-system-situational-awareness

What this skill does

# Skill System Situational Awareness

Generate first-person sensory status narratives from raw system observations — turns abstract system state (bundle IDs, percentages, status tables) into embodied first-person-present-tense description (walls, screens, clocks, desk tools, weather, colleagues).

## When to use

- Status reports to humans
- Session resume briefings
- Reflection prompts after intense execution
- Compaction checkpoints where raw telemetry needs to feel cognitively real

## Dependency boundary

- Reads existing `Work/.tkt/scripts/hermes-*` sensors via subprocess.
- Reads `Work/.tkt/inbox/<role>/inbox.md` and `Work/.tkt/roadmap.yaml`.
- Does **not** replicate sensor logic.
- Fails open when a sensor is missing or down by rendering `(sensor offline)`.

## Usage

```bash
python3 "<this-skill-dir>/scripts/world_scan.py"
python3 "<this-skill-dir>/scripts/world_scan.py" --role sisyphus --mode clinical
python3 "<this-skill-dir>/scripts/world_scan.py" --bundle-file "<this-skill-dir>/examples/sample_observation_bundle.json"
```

## Behavior

- Collects an observation bundle from existing Hermes sensor scripts and inbox / roadmap files.
- Renders the same facts through four tone modes defined in `tone.md`.
- Defaults to `phenomenological` mode and 300–500 word markdown output.
- Emits the markdown body first and a JSON status object on the last stdout line.

```skill-manifest
{
  "schema_version": "2.0",
  "id": "skill-system-situational-awareness",
  "version": "0.1.0",
  "capabilities": ["situational-world-scan"],
  "effects": ["fs.read", "fs.write", "proc.exec"],
  "operations": {
    "world-scan": {
      "description": "Generate a sensory status narrative from existing Hermes sensor outputs and role inbox state.",
      "input": {
        "role": {"type": "string", "required": false, "default": "hermes", "description": "Narrative framing role: hermes or sisyphus"},
        "mode": {"type": "string", "required": false, "default": "phenomenological", "description": "Tone mode from tone.md"},
        "work_root": {"type": "string", "required": false, "description": "Root Work directory containing .tkt/"},
        "bundle_file": {"type": "string", "required": false, "description": "Optional JSON/YAML observation bundle override"},
        "output": {"type": "string", "required": false, "description": "Optional markdown output path"}
      },
      "output": {
        "description": "World-scan generation result",
        "fields": {"status": "ok | error", "role": "string", "mode": "string", "word_count": "integer", "output": "string | null"}
      },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/world_scan.py", "--role", "{role}", "--mode", "{mode}", "--work-root", "{work_root}", "--bundle-file", "{bundle_file}", "--output", "{output}"],
        "windows": ["python", "{skill_dir}/scripts/world_scan.py", "--role", "{role}", "--mode", "{mode}", "--work-root", "{work_root}", "--bundle-file", "{bundle_file}", "--output", "{output}"]
      }
    }
  },
  "assets": {
    "examples_dir": "examples/",
    "test_fixtures_dir": "tests/fixtures/"
  },
  "source_transparency": {
    "generated_at_build": true,
    "github_url": "https://github.com/arthur0824hao/skills",
    "commit_ref": "<auto>",
    "loc": "<auto>",
    "test_coverage_pct": "<auto>"
  },
  "stdout_contract": {
    "last_line_json": true
  }
}
```