sensemaking-skills 0.2.1

Agent-native framework for repository diagnosis and workflow orchestration

Sensemaking Skills

An agent-native framework for repository diagnosis and workflow orchestration. Turns repository uncertainty into clear problem frames, research paths, and actionable next-step prompts.

Status: Beta (Scenario 5 tested and proven)
Current Use: Agent/Claude Code invocation + CLI utilities (v0.2.1)
Maturity: Production-ready for agent-based use, CLI beta-ready

---

What This Is

✅ Proven diagnostic framework — Scenario 5 budget-exhaustion testing confirms:

• Error recovery with bounded retry logic (3 attempts)
• Graceful escalation when limits exhausted
• Real execution on actual repositories with honest metrics

✅ Artifact-driven engineering — All communication happens via durable, validated artifacts:

• repository_sensemaking_brief (14-section diagnostic)
• workflow_orchestration_plan (10-section execution plan)
• Validation ensures quality and safety

✅ Agent-native design — Built for Claude Code and agent invocation:

• Skills defined in SKILL.md files
• Orchestration via artifact handoffs
• No external dependencies

What This Is NOT

❌ Not a fully autonomous CLI diagnosis engine — Repository diagnosis is agent-led, CLI provides utilities
❌ Not published to PyPI yet — Install from source with pip install -e ., publishing after real-world CLI testing
❌ Not a black-box service — Requires Claude Code or agent invocation for actual diagnostics
❌ Not a replacement for specialized tools — Complements PM skills, UI skills, TDD tools

---

Installation

Sensemaking Skills currently supports two working usage modes:

1. Agent-native workflow — Recommended for actual repository diagnosis
2. Local CLI utilities — Available for validation, testing, and environment prep

PyPI publication is prepared, but the package is not yet released to production PyPI. For now, install from source.

Quick Start

# Clone the repository
git clone https://github.com/ThorStarlord/sensemaking-skills.git
cd sensemaking-skills

# Create and activate a Python environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install locally
pip install -e .

# Verify the CLI
sensemaking-skills --version

Expected version: 0.2.1

CLI Commands

# Prepare a repository for agent-led diagnosis
sensemaking-skills analyze --repo /path/to/my/repo

# Validate an artifact after agent creates it
sensemaking-skills validate --artifact artifacts/repository_sensemaking_brief.md

# Run test automation
sensemaking-skills test

---

Current Architecture

Two Invocation Paths

Path 1: Claude Code / Agent

Load skill → Invoke skill as agent → Read SKILL.md → Execute procedure

This is how it's used today.

Path 2: Python Scripts (Direct)

python scripts/shadow-mode-runner.py <repo_path>
python scripts/validate-brief.py <artifact_path>
python scripts/validate-plan.py <artifact_path>

For testing and automation.

---

How to Use

Two Usage Paths

Path 1: Agent-native (Recommended for Diagnosis)

Use Claude Code or another agent environment for full repository diagnosis:

# 1. Clone and open in Claude Code
git clone https://github.com/ThorStarlord/sensemaking-skills.git
cd sensemaking-skills

# 2. Ask your agent to read the bootstrap skill
# Read `skills/using-sensemaking/SKILL.md`

# 3. Then ask the agent to diagnose your target repository
# Use `skills/repo-sensemaker/SKILL.md` to analyze /path/to/my/repo
# Produce artifacts and validate them

Path 2: Local CLI (Utilities)

Use the CLI for validation, testing, and environment preparation:

# After installing locally (pip install -e .), use:
sensemaking-skills analyze --repo /path/to/my/repo
sensemaking-skills validate --artifact artifacts/repository_sensemaking_brief.md
sensemaking-skills test --repos 100

Note: The CLI analyze command prepares the environment and prints instructions for the agent-led diagnosis workflow. It does not generate the brief by itself — the agent (reading the skills) does that work.

Option 1: Use Locally with Claude Code or Another Agent

1. Clone the repository:

   git clone https://github.com/ThorStarlord/sensemaking-skills.git
   cd sensemaking-skills
   

2. Open this repository in your agent environment.

3. Ask the agent to read the bootstrap skill:

   Read `skills/using-sensemaking/SKILL.md`.
   Then use `skills/repo-sensemaker/SKILL.md` to analyze `/path/to/target/repo`.
   Produce a `repository_sensemaking_brief`.
   Validate the artifact with `scripts/validate-and-report.py`.
   

4. For workflow planning, ask the agent to use the generated brief:

   Use `skills/workflow-planner/SKILL.md` to convert the brief into a `workflow_orchestration_plan`.
   Validate the plan with `scripts/validate-and-report.py`.
   

Optional: Install Skills into Claude Code

If your Claude Code environment supports local skill installation, you can copy the skills directory:

mkdir -p ~/.claude/skills
cp -R skills/* ~/.claude/skills/

Then restart or reload Claude Code if needed.

Depending on your Claude Code setup, you may be able to invoke:

/skill repo-sensemaker
/skill workflow-planner

If those commands are not available, use the fallback method above: ask the agent to read the relevant SKILL.md files directly.

Option 2: Validate Existing Artifacts with Python Scripts

Python scripts validate artifacts produced by agents. They do not currently replace the agent-led diagnosis process.

Validate a repository sensemaking brief:

python scripts/validate-and-report.py artifacts/repository_sensemaking_brief.md

Validate a workflow orchestration plan:

python scripts/validate-and-report.py artifacts/workflow_orchestration_plan.md

Run individual validators directly:

python scripts/validate-brief.py artifacts/repository_sensemaking_brief.md --json
python scripts/validate-plan.py artifacts/workflow_orchestration_plan.md --json

Run shadow-mode test automation:

python scripts/shadow-mode-runner.py

---

Core Skills

Diagnostic Skills

• repo-sensemaker — Analyzes repository structure and produces a 14-section diagnostic brief
• workflow-planner — Converts diagnostic brief into a 10-section orchestration plan

Validation Skills

• validate-brief.py — Validates repository_sensemaking_brief artifacts against contract
• validate-plan.py — Validates workflow_orchestration_plan artifacts against contract
• validate-and-report.py — Full validation pipeline with error recovery

---

Repository Structure

sensemaking-skills/
├── skills/
│   ├── repo-sensemaker/
│   │   ├── SKILL.md              (Skill definition)
│   │   ├── agents/               (Agent definitions)
│   │   └── references/           (Fog classification rules)
│   ├── workflow-planner/
│   │   ├── SKILL.md
│   │   ├── agents/
│   │   └── references/           (Workflow registry, artifact contracts)
│   └── [other skills...]
├── scripts/
│   ├── validate-brief.py         (Validation)
│   ├── validate-plan.py          (Validation)
│   ├── shadow-mode-runner.py     (Test automation)
│   └── [utilities...]
├── examples/
│   └── [sample briefs and plans]
├── tests/
│   └── [test suite]
├── docs/
│   ├── CONTEXT.md                (Architecture and principles)
│   ├── philosophy/               (Design philosophy)
│   └── adr/                       (Architecture Decision Records)
└── setup.py / pyproject.toml     (Packaging metadata)

---

Evidence of Correctness

Scenario 5: Budget Exhaustion (Proven)

• ✅ Real artifact with 3 repair attempts
• ✅ Same error persists across attempts
• ✅ No 4th attempt (budget respected)
• ✅ Graceful escalation message

See: SCENARIO-5-CLEAN-TEST-EVIDENCE.md

Week 1: Real Execution

• ✅ 10 real repositories tested
• ✅ Real execution times measured (0.131s avg, 0.138s P95)
• ✅ Honest results documented (infrastructure works, repos lack artifacts)

See: WEEK1-REAL-EXECUTION-EVIDENCE.md

---

Next: Roadmap to User-Ready

Phase 2.1: User-Facing Installation

• Create CLI interface (click/argparse)
• Add entry points in setup.py
• Enable sensemaking-skills analyze --repo /path
• Publish to PyPI

Phase 2.2: Documentation

• Write GETTING_STARTED.md with real examples
• Write INSTALLATION.md with step-by-step guide
• Create API reference documentation
• Add troubleshooting guide

Phase 2.3: Quality Gates

• Add integration tests for CLI
• Test on real projects
• Create user feedback loops

---

Development

Contributing:

• Bug reports: Issues
• Feature requests: Discussions
• Pull requests welcome — please include tests

Philosophy: See docs/philosophy/ARTIFACT_DRIVEN_AGENTIC_ENGINEERING.md for the design principles behind this system.

---

License

MIT License. See LICENSE for details.

---

Quick Links

• CONTEXT.md — Architecture overview and principles
• GETTING_STARTED.md — Real-world examples and workflows
• INSTALLATION.md — Step-by-step setup guide
• API.md — Python API reference
• CLAUDE.md — Agent guidelines and hooks