spec-extracter - SKILL.md Agent Skill

name: Spec Extracter description: This skill should be used when the user asks to "extract spec", "extract requirements", "analyze invariants", "extract preconditions", "스펙 추출", "요구사항 추출", "불변식 추출", "전제조건 추출", "코드에서 스펙 뽑아줘", "요구사항 뽑아줘", or selects a class/method and wants a structured requirements list generated from the code. version: 0.2.0

Spec Extracter

Purpose

Analyze a selected class or method, extract invariants, preconditions, postconditions, dependencies, complexity metrics, and test coverage gaps embedded in the code. Produce a structured specification in the user's chosen format — Markdown checklist or JSON — suitable for documentation, code review, or toolchain integration.

Interactive Workflow

Step 1: Identify the Target

If the user has not explicitly specified a target, ask:

AskUserQuestion:
  question: "분석할 코드를 알려주세요 / Please specify the code to analyze"
  options:
    - label: "파일 경로 + 클래스/메서드 / File path + class/method"
      description: "e.g. src/services/OrderService.ts > placeOrder()"
    - label: "코드 스니펫 직접 입력 / Paste code snippet"
      description: "Paste the code directly in the conversation"

Step 2: Select Output Format

AskUserQuestion:
  question: "출력 포맷을 선택해주세요 / Select output format"
  options:
    - label: "Markdown Checklist (default)"
      description: "REQ-ID 기반 체크리스트 — 문서, PR 설명용 / For documentation and PR reviews"
    - label: "JSON Spec"
      description: "구조화된 JSON — 툴체인 연동, 자동화용 / For toolchain integration and automation"

Step 3: Analyze the Code

Read the target file using the Read tool. Perform full analysis across all dimensions:

Dimension	What to Look For
Preconditions	Guard clauses, `throw` on invalid input, assertions at entry
Postconditions	Return value guarantees, state mutations
Invariants	Class-level constraints held before/after every method call
Input Constraints	Parameter types, null checks, range checks, enum constraints
Error Conditions	Exception types thrown, error codes, failure branches
Side Effects	DB writes, I/O, event emissions, external API calls
Dependencies	External services, repositories, injected dependencies called
Complexity	Branch count, loop depth, cyclomatic complexity estimate
Test Coverage Gap	Spec items with no apparent test coverage

Assign a confidence level to each requirement:

Tag	Meaning
`[HIGH]`	Explicitly enforced in code (guard clause, assertion, type annotation)
`[MED]`	Implied by naming, comment, or usage pattern
`[LOW]`	Inferred from context; needs author verification

Assign a test coverage status if test files are accessible:

Tag	Meaning
`[TESTED]`	Evidence of test coverage found
`[UNTESTED]`	No evidence of coverage — candidate for new test
`[UNKNOWN]`	Test files not available or not checked

For language-specific detection patterns (TypeScript, Java/Kotlin, Python, Go), refer to references/analysis-patterns.md.

Step 4: Output the Spec

Render in the selected format. For full format specifications and JSON schema, refer to references/output-formats.md.

Markdown structure (summary):

## Spec: `ClassName.methodName()`

> File: `path/to/file` | Complexity: ~N | Risk: LOW / MEDIUM / HIGH

### Preconditions
- [ ] REQ-PRE-01 [HIGH] [TESTED]: ...

### Postconditions
- [ ] REQ-POST-01 [HIGH] [UNKNOWN]: ...

### Invariants
- [ ] REQ-INV-01 [MED] [UNKNOWN]: ...

### Input Constraints
- [ ] REQ-IN-01 [HIGH] [TESTED]: ...

### Error Conditions
- [ ] REQ-ERR-01 [HIGH] [UNTESTED]: ...

### Side Effects
- [ ] REQ-SFX-01 [HIGH] [UNTESTED]: ...

### Dependencies
- [ ] REQ-DEP-01 [HIGH]: ...

### Complexity Metrics
- Estimated Cyclomatic Complexity: N
- Branch count: N
- Risk level: LOW / MEDIUM / HIGH

### Implicit Assumptions (not enforced in code)
- ASSUME-01: ... — consider adding a guard clause

**Summary:** [One paragraph: what the method does, what it guarantees, notable risks]

JSON structure: See references/output-formats.md for full schema and example.

Step 5: Save Option

AskUserQuestion:
  question: "결과를 파일로 저장할까요? / Save the spec to a file?"
  options:
    - label: "Yes — save to specs/ directory"
      description: "Default: specs/{ClassName}.{methodName}.spec.md (or .json)"
    - label: "No — continue without saving"

Complexity Metrics

Calculate cyclomatic complexity by starting at 1 and adding +1 for each:

if / else if / case branch
for / while / do...while loop
catch / except block
&& / || logical operator in a condition

Score	Risk
1–5	LOW
6–10	MEDIUM
11–20	HIGH
21+	CRITICAL — split recommended

Dependency Tracking

For each external call identified in the method, produce a REQ-DEP-NN entry describing:

Which dependency is called (ServiceName.method())
What must be true for the call to succeed (initialized, non-null, authenticated, etc.)
Whether a null/initialization check exists in the code

Test Coverage Gap Detection

After generating all spec items, flag items where no test coverage is evident:

Look for test files: *.spec.ts, *_test.go, test_*.py, *Test.java, *.test.js
Cross-reference each spec item (especially REQ-ERR-* and REQ-PRE-*) against test file content
Mark items as [TESTED], [UNTESTED], or [UNKNOWN]
Summarize coverage gaps at the end: "N of M spec items appear untested"

Additional Resources

Reference Files

references/analysis-patterns.md — Language-specific detection patterns for TypeScript, Java/Kotlin, Python, Go; complexity calculation guide; test gap detection heuristics
references/output-formats.md — Complete Markdown format spec, full JSON schema with field descriptions, example output, format selection guide

Examples

examples/typescript-example.md — Full worked example: NestJS OrderService.placeOrder() with both Markdown and JSON output