roster-spec-infer

Roster Spec-Infer

Reverse-engineer an evidence-tiered spec from an existing codebase. This is a read-only analysis skill — it never modifies the target project. Every claim is labeled by evidence strength: [E1] (test-proven), [E2] (code-inferred), [E3] (doc-only). Conflicts between code and documentation are surfaced, never silently resolved.

Input Contract

Required: <target> — a project root directory path (e.g. . or /path/to/project).

• If a file path is given: halt with "Target must be a directory (project root). Got: <path>."
• Slug derivation: lowercase the target directory's basename, replace spaces with -, strip all non-alphanumeric/hyphen characters. Example: My Project! → my-project.
• Collision check: if specs/<slug>-inferred.md already exists, halt with: "Inferred spec already exists for <slug>. Overwrite? [y/N]" — stop if not confirmed.

Tunables:

Tunable	Default	Effect
include_git_history	true	Run Sub-agent 4 (Git History Miner)
conflict_policy	surface	Only supported value: always surface conflicts, never auto-resolve. Reserved for future extension.
gap_threshold	0	Register every uncovered public symbol as a GAP

Steps

Sub-agent 1: Test Miner

Spawn a sub-agent (fresh context) with this prompt:

You are a Test Miner. Analyze the test suite of the target project and extract
behavioral assertions as evidence-tier-1 (E1) claims in Given/When/Then format.

Step 1 — Detect test framework (in this priority order):
- package.json `scripts.test` field
- pytest.ini / setup.cfg / pyproject.toml [tool.pytest]
- go.mod (go test ./...)
- pom.xml / build.gradle (mvn test / gradle test)
If no framework detected: emit "No test suite detected — all surfaces are E2/E3 or GAP."
and produce zero E1 claims. Stop.

Step 2 — Run the canonical test command. If exit code is non-zero: halt with:
"Test suite failed — E1 claims cannot be emitted. Fix test failures before
running roster-spec-infer."

Step 3 — Parse passing test files. For each behavioral assertion, produce one
E1 entry in Given/When/Then format:
  - [E1] Given <setup/precondition>, When <action or call>, Then <assertion/outcome>
    (evidence: <test-file>:<line>)

Use the actual test setup code as "Given", the call under test as "When", and
the assertion as "Then". If a test has multiple assertions, emit one E1 entry
per distinct behavioral claim, not per assertion line.

Cap at top-50 most-covered files if context limits are reached; note:
"Analysis limited to top N files due to context constraints."

Target directory: <target>