Skip to content

borghei/Claude-Skills / project-management/execution/job-stories

job-stories

Verified

Write When/Want/So backlog stories from observed user situations, gated on INVEST and outcome-focused acceptance criteria. Use when writing backlog items from research or converting "As a..." user stories to job stories.

scripts/invest_validator.py

View on GitHub
#!/usr/bin/env python3
"""INVEST Validator - Validate backlog items against INVEST criteria.

Reads stories/items and evaluates each against the 6 INVEST criteria
(Independent, Negotiable, Valuable, Estimable, Small, Testable).

Usage:
    python invest_validator.py --items items.json
    python invest_validator.py --items items.json --format json
    python invest_validator.py --example
"""

import argparse
import json
import re
import sys


def fail(msg: str) -> None:
    """Print a one-line input error and exit 2."""
    print(f"error: {msg}", file=sys.stderr)
    sys.exit(2)


def load_data(path: str, key: str) -> dict:
    try:
        with open(path, "r", encoding="utf-8") as f:
            data = json.load(f)
    except OSError as exc:
        fail(f"cannot read {path}: {exc.strerror or exc}")
    except ValueError as exc:
        fail(f"{path} is not valid JSON: {exc}")
    items = data.get(key) if isinstance(data, dict) else None
    if not isinstance(items, list) or not items or not all(isinstance(i, dict) for i in items):
        fail(f"{path} must be a JSON object with a non-empty '{key}' list of objects")
    for item in items:
        for field in ("acceptance_criteria", "dependencies"):
            if not isinstance(item.get(field, []), list):
                fail(f"{path}: '{field}' in '{item.get('title', 'Untitled')}' must be a list")
    return data


def validate_invest(item: dict) -> dict:
    title = item.get("title", "Untitled")
    description = item.get("description", "")
    acceptance_criteria = item.get("acceptance_criteria", [])
    dependencies = item.get("dependencies", [])
    story_points = item.get("story_points")
    sprint_fit = item.get("fits_in_sprint", None)

    checks = {}

    # Independent
    has_deps = len(dependencies) > 0
    checks["independent"] = {
        "passed": not has_deps,
        "detail": f"Has {len(dependencies)} dependency(ies): {', '.join(dependencies[:3])}" if has_deps else "No blocking dependencies",
        "fix": "Reorder backlog or combine dependent items" if has_deps else None,
    }

    # Negotiable
    impl_words = [r"\buse React\b", r"\buse API\b", r"\buse SQL\b", r"\bimplement with\b", r"\bmust use\b", r"\brequires \w+ library\b"]
    is_prescriptive = any(re.search(p, description, re.IGNORECASE) for p in impl_words)
    checks["negotiable"] = {
        "passed": not is_prescriptive,
        "detail": "Description prescribes implementation approach" if is_prescriptive else "Implementation approach is negotiable",
        "fix": "Remove implementation details from description -- describe the What, not the How" if is_prescriptive else None,
    }

    # Valuable
    has_outcome = bool(item.get("outcome") or item.get("so_that") or item.get("why"))
    value_words = [r"\breduce\b", r"\bincrease\b", r"\bimprove\b", r"\benable\b", r"\bsave\b", r"\beliminate\b"]
    has_value_language = any(re.search(p, description, re.IGNORECASE) for p in value_words)
    checks["valuable"] = {
        "passed": has_outcome or has_value_language,
        "detail": "Clear value proposition" if (has_outcome or has_value_language) else "No clear user or business value stated",
        "fix": "Add a Why or outcome statement connecting to user benefit or business objective" if not (has_outcome or has_value_language) else None,
    }

    # Estimable
    desc_length = len(description)
    has_ac = len(acceptance_criteria) >= 2
    checks["estimable"] = {
        "passed": desc_length >= 50 and has_ac,
        "detail": f"Description: {desc_length} chars, {len(acceptance_criteria)} AC" if desc_length >= 50 and has_ac else "Insufficient detail for estimation",
        "fix": "Add more context to description and at least 4 acceptance criteria" if not (desc_length >= 50 and has_ac) else None,
    }

    # Small
    if sprint_fit is not None:
        is_small = sprint_fit
    elif story_points is not None:
        is_small = story_points <= 8
    else:
        word_count = len(description.split())
        is_small = word_count < 200 and len(acceptance_criteria) <= 10
    checks["small"] = {
        "passed": is_small,
        "detail": f"Story points: {story_points}" if story_points else ("Fits in sprint" if is_small else "May be too large for one sprint"),
        "fix": "Split by user segment, scenario, or outcome to fit in one sprint" if not is_small else None,
    }

    # Testable
    testable_ac = sum(1 for ac in acceptance_criteria if any(re.search(p, ac.lower()) for p in [r"\bshows\b", r"\bdisplays\b", r"\benables\b", r"\bprevents\b", r"\bwithin\b", r"\bwhen\b", r"\bif\b"]))
    has_testable_ac = testable_ac >= 2 or len(acceptance_criteria) >= 4
    checks["testable"] = {
        "passed": has_testable_ac,
        "detail": f"{testable_ac}/{len(acceptance_criteria)} criteria are clearly testable" if acceptance_criteria else "No acceptance criteria",
        "fix": "Rewrite criteria as observable outcomes: '[Thing] [does] [expected behavior] [under condition]'" if not has_testable_ac else None,
    }

    passed = sum(1 for c in checks.values() if c["passed"])
    total = len(checks)
    score = round(passed / total * 100)

    if passed == 6:
        rating = "Sprint Ready"
    elif passed >= 4:
        rating = "Needs Refinement"
    else:
        rating = "Not Ready"

    fixes = [{"criterion": k, "action": v["fix"]} for k, v in checks.items() if v.get("fix")]

    return {
        "title": title,
        "score": score,
        "rating": rating,
        "passed": passed,
        "total": total,
        "checks": checks,
        "fixes": fixes,
    }


def analyze_items(data: dict) -> dict:
    items = data.get("items", [])
    results = [validate_invest(item) for item in items]

    ready = sum(1 for r in results if r["rating"] == "Sprint Ready")
    needs_work = sum(1 for r in results if r["rating"] == "Needs Refinement")
    not_ready = sum(1 for r in results if r["rating"] == "Not Ready")

    return {
        "total_items": len(results),
        "sprint_ready": ready,
        "needs_refinement": needs_work,
        "not_ready": not_ready,
        "items": results,
    }


def print_report(result: dict) -> None:
    print(f"\nINVEST Validation")
    print(f"Items: {result['total_items']}")
    print("=" * 60)
    print(f"Sprint Ready: {result['sprint_ready']}  |  Needs Refinement: {result['needs_refinement']}  |  Not Ready: {result['not_ready']}")

    for item in result["items"]:
        print(f"\n  [{item['rating']}] {item['title']} ({item['passed']}/{item['total']} INVEST)")
        for criterion, check in item["checks"].items():
            status = "PASS" if check["passed"] else "FAIL"
            print(f"    [{status}] {criterion.upper()}: {check['detail']}")
        if item["fixes"]:
            print(f"    Fixes needed:")
            for fix in item["fixes"]:
                print(f"      - {fix['criterion'].upper()}: {fix['action']}")
    print()


def print_example() -> None:
    example = {
        "items": [
            {
                "title": "Weekly Budget Summary",
                "description": "When preparing my weekly budget, I want to see spending by category so I can adjust before overspending. The view should group transactions and highlight over-budget categories.",
                "outcome": "Reduce time spent on budget review from 30 minutes to 5 minutes",
                "acceptance_criteria": [
                    "Shows current month transactions grouped by category",
                    "Displays total spent and remaining budget per category",
                    "Over-budget categories are visually highlighted",
                    "Tapping a category shows individual transactions",
                    "Loads within 2 seconds on mobile",
                ],
                "dependencies": [],
                "story_points": 5,
            },
            {
                "title": "Complete Platform Redesign",
                "description": "Redesign the entire platform. Use React and implement with a new API.",
                "acceptance_criteria": ["It works"],
                "dependencies": ["Database migration", "API v2 release"],
                "story_points": 40,
            },
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(
        description="Validate backlog items against the six INVEST criteria. Exit 0 all sprint-ready, 1 at least one is not, 2 bad input.")
    parser.add_argument("--items", type=str, help="Path to JSON file: {'items': [...]} (see --example)")
    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format (default: text)")
    parser.add_argument("--json", action="store_true", help="Shorthand for --format json")
    parser.add_argument("--example", action="store_true", help="Print an example input file and exit")
    args = parser.parse_args()

    if args.example:
        print_example()
        return 0
    if not args.items:
        parser.error("--items is required (or --example)")

    result = analyze_items(load_data(args.items, "items"))
    if args.json or args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        print_report(result)
    return 0 if result["sprint_ready"] == result["total_items"] else 1


if __name__ == "__main__":
    sys.exit(main())
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall