First-Principles Briefing Skill

Trigger

• Keywords: first principles, fp brief, why was this decided, reasoning chain, decision sensitivity, explain decisions, assumption analysis, onboarding brief

When NOT to Use

Command Signature

/fp-brief <doc-path> [--depth brief|normal|deep] [--verify off|codex] [--output <path>] [--no-save]

Workflow

sequenceDiagram
    participant U as User
    participant S as /fp-brief
    participant D as Source Doc
    participant O as Output File
    participant X as Codex (optional)

    U->>S: /fp-brief <doc-path> [--depth] [--verify]
    Note over S: Phase 1: Input Resolution
    S->>S: Validate path (repo boundary)
    S->>D: Read source document
    S->>S: Redaction scan (fail-safe)
    S->>S: Auto-detect format (hybrid)
    Note over S: Phase 2: First-Principles Extraction
    S->>S: Extract Root Problem (5-Why)
    S->>S: Build Assumptions Register
    S->>S: Build Reasoning Chain
    S->>S: Build Alternative Rejection Log
    S->>S: Build Decision Sensitivity
    S->>S: Identify Open Unknowns
    Note over S: Phase 3: Output Assembly
    S->>O: Write *-fp-brief.md
    alt --verify codex
        S->>X: Independent reasoning verification
        X-->>S: Verification Delta
        S->>O: Append Verification Delta
    end
    S-->>U: Report complete

Phase 1: Input Resolution

1. Path validation: Normalize, reject .. traversal, enforce repo boundary
2. Read source document
3. Redaction scan: High-confidence secret patterns → abort; medium → mask [REDACTED]
4. Format auto-detection: See references/detection-rules.md
5. Select extraction template based on detected format

Phase 2: First-Principles Extraction

See references/extraction-guide.md for section-by-section heuristics.

For long documents (>500 lines): split by ## headings, extract per-section, merge + dedup.

Phase 3: Output Assembly

1. Apply depth filter (section inclusion matrix)
2. Apply source citations (reference source doc section headings)
3. Apply Evidence Insufficient Rule — never fabricate content for thin sections
4. Write output file (or stdout if --no-save — which --verify codex rejects, see § Save Behavior)
5. If --verify codex: dispatch verification per references/codex-verify-prompt.md

Depth Levels

Verification Delta (section 7) appears only when --verify codex is used, at any depth level.

Length policy: These are upper bounds, not targets. If source doc is thin, output will be shorter. The Evidence Insufficient Rule applies: [Evidence insufficient — source doc lacks data for this section].

Output

See references/output-template.md for full template.

# First-Principles Briefing: <title>

> Source: <path> | Depth: <level> | Format: <type> | Generated: <timestamp>

## 1. Root Problem
## 2. Assumptions Register
## 3. Reasoning Chain
## 4. Alternative Rejection Log
## 5. Decision Sensitivity
## 6. Open Unknowns
## 7. Verification Delta (optional)

Save Behavior

Example: docs/features/auth/2-tech-spec.md → docs/features/auth/2-tech-spec-fp-brief.md

Verification

• Input path validated (repo boundary enforced)
• Secret redaction scan executed
• Format auto-detection result shown in output header
• Each Reasoning Chain decision cites source section (Source: §<ref>)
• Each Assumptions Register entry has confidence level
• Decision Sensitivity maps assumptions to affected decisions
• Evidence Insufficient markers used where source data is thin
• Output length within depth-level upper bound
• If --verify codex: Codex researched independently (per codex-invocation rules)

References

• Output template: references/output-template.md
• Detection rules: references/detection-rules.md
• Extraction guide: references/extraction-guide.md
• Codex verification: references/codex-verify-prompt.md

Examples

Input: /fp-brief docs/features/seek-verdict/2-tech-spec.md
Action: Read spec → detect tech-spec → extract 6 sections → write 2-tech-spec-fp-brief.md

Input: /fp-brief docs/features/auth/2-tech-spec.md --depth brief
Action: Read spec → extract Root Problem + top assumptions + key decisions + top sensitivity → brief output

Input: /fp-brief docs/features/auth/2-tech-spec.md --depth deep --verify codex
Action: Read spec → full extraction → Codex independent verification → write with Verification Delta

Input: /fp-brief notes/design-decisions.md --no-save
Action: Read doc → detect unknown format → generic extraction → print to stdout