tech-brief

Technical Briefing Skill

Trigger

• Keywords: tech brief, technical briefing, share with team, tech-brief, dev sharing, share findings, technical memo

When NOT to Use

Scenario	Alternative
PM/CTO executive summary (strip technical details)	/project-brief
First-principles reasoning chain (why decisions were made)	/fp-brief
Design-phase technical specification (before implementation)	/tech-spec
Code explanation at function/file level	/codex-explain
Simple document summary	Ask Claude directly

Command Signature

/tech-brief [<feature-key>|<docs-path>] [--depth brief|normal|deep] [--output <path>] [--no-save]

Flag	Default	Description
<feature-key>	Auto-detect	Feature key or docs path
--depth	normal	Output depth (brief/normal/deep)
--output	docs/features/<key>/5-tech-brief.md	Custom output path
--no-save	false	Print to stdout only

Workflow

sequenceDiagram
    participant U as User
    participant S as /tech-brief
    participant FR as feature-resolver.js
    participant D as Feature Docs
    participant G as Git History
    participant C as Changed Files
    participant O as Output File

    U->>S: /tech-brief [feature] [--depth] [--output]
    Note over S: Phase 1: Context Resolution
    S->>FR: Resolve feature (5-level cascade)
    FR-->>S: Feature key + doc inventory
    Note over S: Phase 2: Multi-Source Collection
    S->>D: Stage 1 — Read docs (tech-spec, architecture, requests)
    S->>G: Stage 2 — git log + diff + changed file reading
    S->>D: Stage 3 — Request selection (top 3 by date)
    Note over S: Phase 3: Synthesis
    S->>S: Build Source Provenance table
    S->>S: Extract & organize by output template
    S->>S: Apply depth filter
    Note over S: Phase 4: Output
    S->>O: Write tech-brief file
    S-->>U: Report complete

Phase 1: Context Resolution

1. Parse $ARGUMENTS for feature-key, path, or flags
2. Resolve feature using node scripts/resolve-feature.js [--feature <key>] — the wrapper, not the CLI: it owns the failure payload. If scan_error !== false — including a payload with no such field, which is what a shell || echo '{}' fallback produces — the four source sets are unknown, not empty. Stop and take the ⚠️ Need Human exit; a non-null key is not evidence the sets are complete
3. Load doc_inventory and the four source sets from resolver output
4. Validate paths (see Path Security)

Input Resolution Table

Input Type	Example	Feature Resolution	Default Output Path
Feature key	/tech-brief fp-brief	--feature fp-brief	docs/features/fp-brief/5-tech-brief.md
Feature dir	/tech-brief docs/features/fp-brief/	Extract key from path	docs/features/fp-brief/5-tech-brief.md
Feature doc	/tech-brief docs/features/fp-brief/2-tech-spec.md	Extract key from parent	docs/features/fp-brief/5-tech-brief.md
Non-feature	/tech-brief /tmp/notes.md	No feature context	Require --output
No argument	/tech-brief	Auto-detect (5-level cascade)	Based on resolved feature

Phase 2: Multi-Source Collection

Three-stage collection. See references/source-guide.md for detailed strategy.

Stage 1 — Document Collection: Read design_records (tech-spec, architecture, feasibility) for the why and current_authority for the what it does now. All optional — and a brief that presents a design record's claim as shipped behaviour is the failure mode to avoid; Stage 2's code evidence is what settles the difference.

Stage 2 — Code & Git Evidence: git log -20, git diff --stat, read top 5 changed source files (100 lines each) for file:line references.

Stage 3 — Request Selection: Glob all request docs (no status filter — completed features are the primary use case), max 3 by date desc. Extract ## References for threadIds and PR links.

Phase 3: Synthesis

1. Build Source Provenance table (Section | Source Files | Confidence)
2. For each output section, extract content from mapped sources (see references/output-template.md)
3. Apply depth filter (section inclusion and detail level per depth matrix)
4. Apply Evidence Insufficient Rule: [Source unavailable — no <type> found for this feature]

Phase 4: Output

See Save Behavior for output path resolution.

Path Security

1. Path normalization: Resolve .. and symlinks, verify repo boundary
2. Traversal rejection: Input containing .. is rejected
3. Output path: --output allows repo-external paths (e.g. /tmp/), emit warning "writing outside repo"
4. Secret redaction: Before reading source docs, scan for high-confidence secret patterns (API keys, private keys) — high confidence: abort; medium confidence: mask [REDACTED]

Depth Levels

Level	Max Length	Description
brief	~500 words	Key points only — suitable for Slack sharing
normal	~1500 words	Full coverage with source citations
deep	~3000 words	Full coverage + code snippets + alternative comparison

These are upper bounds, not targets. Source-thin features will produce shorter output.

Output

See references/output-template.md for full template and depth matrix.

# Tech Brief: <Feature Title>

> Feature: <key> | Depth: <level> | Generated: <timestamp>
> Sources: <list of docs read>

## Source Provenance
| Section | Source Files | Confidence |

## 1. Background & Problem
## 2. Design Decisions & Trade-offs
## 3. Implementation Highlights
## 4. Limitations & Known Issues
## 5. Discussion & References
## 6. Next Steps

Save Behavior

Condition	Output Path
Default (feature resolved)	docs/features/<key>/5-tech-brief.md
--output <path>	Specified path (warn if outside repo)
--no-save	stdout only, no file written
No feature + no --output	Gate: Need Human

Preferred canonical name: 5-tech-brief.md. If 5- prefix is occupied, use next available number.

Verification

• Feature context resolved (5-level cascade or explicit)
• Path validation executed (no traversal, repo boundary)
• Secret redaction scan completed
• Source Provenance table present in output
• Each section cites source (or shows Missing Source marker)
• Output length within depth-level upper bound
• Evidence Insufficient markers used where source is thin

References

• Output template: references/output-template.md
• Source collection guide: references/source-guide.md
• Feature context resolution: @skills/create-request/references/feature-context-resolution.md

Examples

Input: /tech-brief seek-verdict
Action: Resolve feature → read tech-spec + request → git log → write 5-tech-brief.md

Input: /tech-brief --depth brief --output /tmp/sharing.md
Action: Auto-detect feature → collect sources → brief output → write /tmp/sharing.md

Input: /tech-brief docs/features/auto-loop-evolution/ --depth deep
Action: Extract key → read all docs + requests (top 3) → deep output with code snippets

Input: /tech-brief --no-save
Action: Auto-detect → collect → print to stdout (no file)