CLI tool that scores app_spec.txt complexity: counts features, external deps, integration points, estimated iteration budget. Flags specs likely to exceed 5 iterations and suggests cuts.

Quick Start • Features • Examples • Contributing

What is this?

SpecShrink is a command‑line utility that reads a specification text file, counts its features/external dependencies/integration points, and estimates how many development iterations it will likely require. It is aimed at product leads and engineers who want to catch overly ambitious specifications before they consume CI resources.

SpecShrink has two subcommands: parse (raw metrics only) and score (metrics plus a pass/fail verdict and cut suggestions).

$ specshrink parse tests/fixtures/test_spec.txt
Features: 2
External deps: 1
Integration points: 1

$ specshrink score tests/fixtures/test_spec.txt
Estimated iterations: 5
Verdict: PASS (≤5)

Problem

Autonomous build pipelines frequently fail on over-scoped specs, wasting compute and tokens on ideas that were never buildable in a handful of iterations. No tool exists to pre-screen spec complexity before committing to a build.

Features

Feature	Description
Spec parsing	Reads a plain-text spec file and extracts structured metrics
Feature counting	Tallies Feature: lines in the spec
Dependency detection	Identifies external URLs/services mentioned
Integration point analysis	Counts distinct integration references
Iteration estimation	Applies a heuristic to predict required development cycles
Over‑scope flagging	Emits a FAIL verdict when the estimated budget exceeds the threshold
Improvement suggestions	Lists concrete items to cut, shown on FAIL

Quick Start

1. Clone the repository:
   git clone https://github.com/m2ai-portfolio/SpecShrink.git
2. Install the package in editable mode:
   cd SpecShrink && pip install -e .
3. Run the tool on a spec file:
   specshrink parse your_spec.txt
specshrink score your_spec.txt

Examples

Basic parsing

$ specshrink parse tests/fixtures/test_spec.txt
Features: 2
External deps: 1
Integration points: 1

Scoring with the default threshold (5 iterations)

$ specshrink score tests/fixtures/test_spec.txt
Estimated iterations: 5
Verdict: PASS (≤5)

Custom threshold

There is no --threshold flag. The threshold is set via the SPECSHRINK_THRESHOLD environment variable (default 5):

$ SPECSHRINK_THRESHOLD=1 specshrink score tests/fixtures/test_spec.txt
Estimated iterations: 5
Verdict: FAIL (>1)
Suggestions:
- Remove integration point: Uses database mysql
- Remove external dependency: Uses https://api.payment.com

There is no --format json output and no bare specshrink FILE invocation — you must use the parse or score subcommand.

File Structure

SpecShrink/
  assets/               # Infographic used in the README
  specshrink/           # Core source code
    __init__.py
    cli.py              # Command‑line interface entry point
    parser.py           # Parses app_spec.txt into a data model
    scorer.py           # Computes complexity metrics and iteration budget
    suggester.py        # Generates actionable reduction suggestions
  tests/                # Unit test suite
    fixtures/           # Sample spec files for testing
    test_parser.py
    test_scorer.py
    test_suggester.py
  pyproject.toml        # Project configuration and dependencies
  README.md
  init.sh               # Helper script to set up a development environment

There is no app_spec.txt shipped in the repo; use tests/fixtures/test_spec.txt as a sample, or write your own.

Tech Stack

Technology	Purpose
Python 3.11+	Core language implementation
Click	Building the CLI interface
Rich	Formatted console output

Contributing

Fork the repository, make your changes, run the test suite, and submit a pull request.
Ensure new features include corresponding unit tests.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio