# Tn Bug Scan

> Deep bug hunt for the telcoin-network codebase (Rust + Solidity submodule) across 9 phases with specialized agents. Bug-hunter framing — asks 'how does this fail in production?' not 'how does an attacker exploit this?'. Covers concurrency, determinism, consensus correctness, state atomicity, panic surface, fork risk, and error propagation. Produces bug tickets with repro + failure mode per findin…

- **Type:** Skill
- **Install:** `agentstack add skill-grantkee-claude-extensions-tn-bug-scan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [grantkee](https://agentstack.voostack.com/s/grantkee)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [grantkee](https://github.com/grantkee)
- **Source:** https://github.com/grantkee/claude-extensions/tree/main/skills/tn-bug-scan

## Install

```sh
agentstack add skill-grantkee-claude-extensions-tn-bug-scan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# tn-bug-scan

Deep bug hunt for telcoin-network. Nine phases of iterative Feynman + state-check analysis, reframed from adversarial auditing to production-failure hunting. Output: bug tickets with concrete repro conditions, failure mode, affected invariant, and recommended fix.

## Activation

- User says `/tn-bug-scan`, `tn bug scan`, `telcoin bug hunt`, `bug scan telcoin`, or `hunt bugs in tn`
- User wants to find correctness failures (crash / stall / fork / divergence / silent wrong state) in telcoin-network code

Different from `/tn-nemesis-scan`: tn-bug-scan produces bug tickets framed around production events; tn-nemesis-scan produces attack paths framed around adversaries. Same codebase, different lens.

## Invocation Format

```
/tn-bug-scan [target] [--full] [--path ] [--hints "..."] [--fresh]
```

Default target = **current branch PR diff vs main** (`.rs` and `.sol` files only).

Examples:
- `/tn-bug-scan` — scan the current branch's changes vs main
- `/tn-bug-scan --full` — scan all of `crates/` + `tn-contracts/src/`
- `/tn-bug-scan --path "crates/consensus/primary/**/*.rs"` — glob-scoped scan
- `/tn-bug-scan crates/state-sync/ --hints "certificate fetcher race"` — explicit target + hints
- `/tn-bug-scan --fresh` — force Phase -1 domain-pattern regeneration

## Execution

### Step 1: Resolve Target Scope

- **`--full`** → target = `crates/` + `tn-contracts/src/` (entire Rust + Solidity tree, excluding tests)
- **`--path `** → target = the glob (can repeat the flag for multiple globs)
- **Explicit `[target]` arg** → target = the user-supplied arg
- **No arg, no flag** → target = current branch PR diff vs `main`, filtered to `.rs` and `.sol`:
  ```bash
  git -C /Users/grant/coding/telcoin/telcoin-network diff --name-only main...HEAD \
    | grep -E '\.(rs|sol)$' \
    | grep -v -E '(test|bench|e2e-tests|test_utils)'
  ```
  If the diff is empty, tell the user the branch has no Rust/Solidity changes and stop.

### Step 2: Parse Optional Arguments

- **`--hints`** — extract the quoted string after `--hints`. Default: `"none"`.
- **`--fresh`** — if present, skip the cache check and force Phase -1 re-discovery.

### Step 3: Resolve Paths

- Target repo path: `/Users/grant/coding/telcoin/telcoin-network`
- Skill references path (absolute): compute from this skill's location; should resolve to `.../skills/tn-bug-scan/references/`

### Step 4: Create Output Directories

```bash
mkdir -p /Users/grant/coding/telcoin/telcoin-network/.audit/tn-bug-scan/research
mkdir -p /Users/grant/coding/telcoin/telcoin-network/.audit/findings
```

### Step 5: Cache Check

Determine if Phase -1 domain discovery is needed.

```bash
if [ -f /Users/grant/coding/telcoin/telcoin-network/.audit/bug-domain-patterns.md ]; then
  head -5 /Users/grant/coding/telcoin/telcoin-network/.audit/bug-domain-patterns.md
fi
git -C /Users/grant/coding/telcoin/telcoin-network rev-parse --short HEAD
```

The cache is **valid** when ALL of:
- The file exists
- The `_Git hash:_` line matches current `git rev-parse --short HEAD`
- The `_Target scope:_` line matches the requested scope
- The `_User hints:_` line matches the provided hints
- The `--fresh` flag was NOT passed

Set `discovery_needed = true` if the cache is invalid or missing. Set `discovery_needed = false` if the cache is valid.

### Step 6: Spawn the Orchestrator

```
Agent({
  subagent_type: "tn-bug-orchestrator",
  description: "Run tn-bug-scan pipeline",
  prompt: "Run the full tn-bug-scan pipeline on the following target scope.

Target scope: [resolved target from Step 1 — list of files/directories]
Target repo path: /Users/grant/coding/telcoin/telcoin-network
References path: [absolute path to skills/tn-bug-scan/references/]
Domain hints: [user hints or 'none']
Discovery needed: [true/false]

All agents MUST read references/bug-core-rules.md, references/bug-patterns.md, and references/tn-hotspots.md.
Phase 7 (reporter) MUST follow references/bug-ticket-format.md exactly.

[If discovery_needed is true:]
Run Phase -1 (Domain Discovery) FIRST:
- Phase -1a: Spawn tn-bug-strategy with target scope, hints, references path
- Phase -1b: Spawn parallel tn-bug-researcher agents (one per research topic)
- Phase -1c: Compile fragments into .audit/bug-domain-patterns.md with cache metadata

[If discovery_needed is false:]
Skip Phase -1. Domain patterns cached at .audit/bug-domain-patterns.md. Verify the file exists and is non-empty before proceeding; if missing, run Phase -1 anyway.

Then execute all 9 phases in order, with all agents reading .audit/bug-domain-patterns.md for domain context:
- Phase 0+1 (parallel): tn-bug-recon + tn-bug-mapper
- Phase 2: tn-bug-feynman (full mode)
- Phase 3: tn-bug-state-check (full mode)
- Phase 4: feedback loop (max 3 iterations; spawn tn-bug-feynman and tn-bug-state-check in targeted mode per iteration)
- Phase 5: tn-bug-scenario
- Phase 6: tn-bug-verifier (loads tn-domain-* skills as needed for invariant cross-check)
- Phase 7: tn-bug-reporter

Write phase outputs to /Users/grant/coding/telcoin/telcoin-network/.audit/tn-bug-scan/
Write final reports to:
  /Users/grant/coding/telcoin/telcoin-network/.audit/findings/tn-bug-scan-verified.md
  /Users/grant/coding/telcoin/telcoin-network/.audit/findings/tn-bug-scan-raw.md

Present a concise summary when complete."
})
```

### Step 7: Relay Orchestrator Summary

After the orchestrator returns, relay its summary to the user with paths to both report files. If CRITICAL findings include an escalation recommendation to `tn-security-eval`, surface that recommendation in the summary.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [grantkee](https://github.com/grantkee)
- **Source:** [grantkee/claude-extensions](https://github.com/grantkee/claude-extensions)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-grantkee-claude-extensions-tn-bug-scan
- Seller: https://agentstack.voostack.com/s/grantkee
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.