Wwas

#!/usr/bin/env python3
"""Backlog Alignment Checker - Check WWAS backlog items for strategic alignment.

Reads WWAS items and validates each Why statement against defined OKRs,
identifying orphaned items and strategic gaps.

Usage:
    python backlog_alignment_checker.py --backlog backlog.json
    python backlog_alignment_checker.py --backlog backlog.json --json
    python backlog_alignment_checker.py --example
"""

import argparse
import json
import re
import sys


def load_data(path: str) -> dict:
    with open(path, "r") as f:
        return json.load(f)


def check_alignment(data: dict) -> dict:
    okrs = data.get("okrs", [])
    items = data.get("items", [])

    okr_keywords = {}
    for okr in okrs:
        okr_id = okr.get("id", "")
        okr_name = okr.get("name", "")
        keywords = okr.get("keywords", [])
        # Also extract words from the OKR name
        name_words = [w.lower() for w in re.findall(r'\w+', okr_name) if len(w) > 3]
        okr_keywords[okr_id] = {
            "name": okr_name,
            "keywords": [k.lower() for k in keywords] + name_words,
        }

    results = []
    aligned = 0
    unaligned = 0
    okr_coverage = {okr_id: 0 for okr_id in okr_keywords}

    for item in items:
        title = item.get("title", "Untitled")
        why = item.get("why", "").lower()
        what = item.get("what", "")
        acceptance_criteria = item.get("acceptance_criteria", [])
        explicit_okr = item.get("okr_ref", "")

        # Check explicit OKR reference
        matched_okrs = []
        if explicit_okr and explicit_okr in okr_keywords:
            matched_okrs.append(explicit_okr)

        # Check keyword matching
        for okr_id, okr_info in okr_keywords.items():
            if okr_id in matched_okrs:
                continue
            for kw in okr_info["keywords"]:
                if kw in why:
                    matched_okrs.append(okr_id)
                    break

        is_aligned = len(matched_okrs) > 0

        # Quality checks on Why
        why_quality = "Good"
        why_issues = []
        if not why or len(why) < 20:
            why_quality = "Missing"
            why_issues.append("Why statement is missing or too short")
        elif any(phrase in why for phrase in ["customer asked", "best practice", "need this", "just because"]):
            why_quality = "Weak"
            why_issues.append("Why uses generic rationale -- connect to a specific metric or OKR")

        # WWAS completeness
        has_why = len(why) >= 20
        has_what = len(what) >= 30
        has_ac = len(acceptance_criteria) >= 4
        completeness = sum([has_why, has_what, has_ac])

        if is_aligned:
            aligned += 1
            for okr_id in matched_okrs:
                okr_coverage[okr_id] = okr_coverage.get(okr_id, 0) + 1
        else:
            unaligned += 1

        results.append({
            "title": title,
            "is_aligned": is_aligned,
            "matched_okrs": [okr_keywords[oid]["name"] for oid in matched_okrs if oid in okr_keywords],
            "why_quality": why_quality,
            "why_issues": why_issues,
            "completeness": {
                "has_why": has_why,
                "has_what": has_what,
                "has_acceptance_criteria": has_ac,
                "score": f"{completeness}/3",
            },
        })

    # OKR coverage analysis
    uncovered_okrs = [okr_keywords[oid]["name"] for oid, count in okr_coverage.items() if count == 0]
    heavily_loaded = [(okr_keywords[oid]["name"], count) for oid, count in okr_coverage.items() if count > 5]

    alignment_rate = round(aligned / len(items) * 100, 1) if items else 0

    recs = []
    if unaligned > 0:
        recs.append(f"{unaligned} backlog item(s) not aligned to any OKR. Review and either connect to objectives or deprioritize.")
    if uncovered_okrs:
        recs.append(f"OKRs with no backlog items: {', '.join(uncovered_okrs[:3])}. Create WWAS items to support these objectives.")
    if heavily_loaded:
        for name, count in heavily_loaded:
            recs.append(f"OKR '{name}' has {count} items. Check if scope is too broad or items need re-scoping.")
    weak_whys = [r for r in results if r["why_quality"] == "Weak"]
    if weak_whys:
        recs.append(f"{len(weak_whys)} item(s) with weak Why statements. Strengthen with specific metrics, OKR references, or customer evidence.")

    return {
        "total_items": len(items),
        "aligned": aligned,
        "unaligned": unaligned,
        "alignment_rate_pct": alignment_rate,
        "okr_coverage": {okr_keywords[oid]["name"]: count for oid, count in okr_coverage.items()},
        "uncovered_okrs": uncovered_okrs,
        "items": results,
        "recommendations": recs,
    }


def print_report(result: dict) -> None:
    print(f"\nBacklog Alignment Check")
    print(f"Items: {result['total_items']}  |  Alignment: {result['alignment_rate_pct']:.0f}%")
    print("=" * 65)
    print(f"Aligned: {result['aligned']}  |  Unaligned: {result['unaligned']}")

    print(f"\nOKR Coverage:")
    for okr, count in result["okr_coverage"].items():
        bar = "#" * min(count, 20)
        indicator = " (NO ITEMS)" if count == 0 else ""
        print(f"  {okr[:35]:<35} {count:>3} items  {bar}{indicator}")

    print(f"\nItem Details:")
    for item in result["items"]:
        status = "OK" if item["is_aligned"] else "!!"
        okrs = ", ".join(item["matched_okrs"]) if item["matched_okrs"] else "NONE"
        print(f"  [{status}] {item['title'][:35]:<35} Why: {item['why_quality']:<8} OKRs: {okrs}")
        for issue in item["why_issues"]:
            print(f"       ! {issue}")

    if result["recommendations"]:
        print(f"\nRecommendations:")
        for i, r in enumerate(result["recommendations"], 1):
            print(f"  {i}. {r}")
    print()


def print_example() -> None:
    example = {
        "okrs": [
            {"id": "OKR-1", "name": "Reduce churn to <5% monthly", "keywords": ["churn", "retention", "activation"]},
            {"id": "OKR-2", "name": "Grow ARR to $10M", "keywords": ["revenue", "ARR", "enterprise", "upsell"]},
            {"id": "OKR-3", "name": "Improve developer experience", "keywords": ["developer", "DX", "API", "documentation"]},
        ],
        "items": [
            {
                "title": "Guided Onboarding Wizard",
                "why": "Our Q2 objective is to reduce churn. 60% of churned users never completed setup.",
                "what": "Add a step-by-step setup wizard for new users.",
                "acceptance_criteria": ["Wizard appears on first login", "Can be skipped", "Progress saved", "Completion confirmation shown"],
                "okr_ref": "OKR-1",
            },
            {
                "title": "Admin Dashboard Polish",
                "why": "Because the customer asked for it.",
                "what": "Clean up the admin dashboard UI.",
                "acceptance_criteria": ["Looks better"],
            },
            {
                "title": "API Rate Limit Docs",
                "why": "Developer support tickets about rate limits increased 40% last quarter, costing 10 hours/week.",
                "what": "Create comprehensive rate limit documentation with examples and troubleshooting guide.",
                "acceptance_criteria": ["Docs cover all endpoints", "Includes code examples", "FAQ section", "Linked from API portal"],
            },
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(description="Check WWAS backlog alignment with OKRs.")
    parser.add_argument("--backlog", type=str, help="Path to backlog JSON file")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--example", action="store_true", help="Print example and exit")
    args = parser.parse_args()

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

    data = load_data(args.backlog)
    result = check_alignment(data)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""INVEST Gate Checker - Validate WWAS items against INVEST quality gates.

Reads WWAS backlog items and checks each against the 6 INVEST criteria
with actionable fix suggestions for failing items.

Usage:
    python invest_gate_checker.py --items items.json
    python invest_gate_checker.py --items items.json --json
    python invest_gate_checker.py --example
"""

import argparse
import json
import re
import sys


def load_data(path: str) -> dict:
    with open(path, "r") as f:
        return json.load(f)


def check_invest(item: dict) -> dict:
    title = item.get("title", "Untitled")
    why = item.get("why", "")
    what = item.get("what", "")
    acceptance_criteria = item.get("acceptance_criteria", [])
    dependencies = item.get("dependencies", [])
    story_points = item.get("story_points")

    gates = {}

    # Independent
    blocked = len(dependencies) > 0
    gates["independent"] = {
        "passed": not blocked,
        "detail": f"Blocked by: {', '.join(dependencies)}" if blocked else "No blocking dependencies",
        "action": "Reorder backlog or combine dependent items" if blocked else None,
    }

    # Negotiable
    prescriptive_patterns = [r"\bmust use\b", r"\bimplement with\b", r"\buse \w+ framework\b", r"\brequires?\s+\w+\s+library\b"]
    is_prescriptive = any(re.search(p, what, re.IGNORECASE) for p in prescriptive_patterns)
    gates["negotiable"] = {
        "passed": not is_prescriptive,
        "detail": "What prescribes implementation approach" if is_prescriptive else "Implementation approach is open",
        "action": "Remove technology/implementation specifics from What -- describe the outcome, not the solution" if is_prescriptive else None,
    }

    # Valuable
    has_value = len(why) >= 30 and not any(re.search(p, why, re.IGNORECASE) for p in [r"customer asked", r"best practice", r"we need this"])
    gates["valuable"] = {
        "passed": has_value,
        "detail": "Why connects to business objective" if has_value else "Why is missing or lacks strategic context",
        "action": "Rewrite Why to reference a specific OKR, metric, or customer evidence" if not has_value else None,
    }

    # Estimable
    enough_context = len(what) >= 50 and len(acceptance_criteria) >= 3
    gates["estimable"] = {
        "passed": enough_context,
        "detail": f"What: {len(what)} chars, {len(acceptance_criteria)} AC" if enough_context else "Insufficient detail for estimation",
        "action": "Add more context to What and provide at least 4 acceptance criteria" if not enough_context else None,
    }

    # Small
    if story_points is not None:
        is_small = story_points <= 8
        size_detail = f"Story points: {story_points}"
    else:
        # Heuristic: many AC = potentially large
        is_small = len(acceptance_criteria) <= 8 and len(what) < 500
        size_detail = f"{len(acceptance_criteria)} AC, {len(what)} chars description"
    gates["small"] = {
        "passed": is_small,
        "detail": size_detail if is_small else f"Likely too large: {size_detail}",
        "action": "Split by user segment, scenario, or outcome to fit one sprint" if not is_small else None,
    }

    # Testable
    observable_patterns = [r"\bshows\b", r"\bdisplays\b", r"\benables\b", r"\bprevents\b", r"\bnotifies\b", r"\bwithin\b", r"\bwhen\b", r"\bif\b", r"\bless than\b", r"\bmore than\b"]
    testable_count = sum(1 for ac in acceptance_criteria if any(re.search(p, ac, re.IGNORECASE) for p in observable_patterns))
    is_testable = testable_count >= 2 or len(acceptance_criteria) >= 4
    gates["testable"] = {
        "passed": is_testable,
        "detail": f"{testable_count}/{len(acceptance_criteria)} criteria clearly testable" if acceptance_criteria else "No acceptance criteria",
        "action": "Rewrite criteria as observable outcomes: '[Thing] [does] [expected behavior] [under condition]'" if not is_testable else None,
    }

    passed = sum(1 for g in gates.values() if g["passed"])
    total = len(gates)

    if passed == 6:
        verdict = "PASS - Sprint Ready"
    elif passed >= 4:
        verdict = "CONDITIONAL - Fix before sprint"
    else:
        verdict = "FAIL - Needs refinement"

    actions = [{"gate": k, "action": v["action"]} for k, v in gates.items() if v.get("action")]

    return {
        "title": title,
        "passed": passed,
        "total": total,
        "verdict": verdict,
        "gates": gates,
        "required_actions": actions,
    }


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

    pass_count = sum(1 for r in results if "PASS" in r["verdict"])
    conditional = sum(1 for r in results if "CONDITIONAL" in r["verdict"])
    fail_count = sum(1 for r in results if "FAIL" in r["verdict"])

    # Most common failing gates
    gate_fails = {}
    for r in results:
        for gate, info in r["gates"].items():
            if not info["passed"]:
                gate_fails[gate] = gate_fails.get(gate, 0) + 1

    return {
        "total_items": len(results),
        "passed": pass_count,
        "conditional": conditional,
        "failed": fail_count,
        "common_failures": sorted(gate_fails.items(), key=lambda x: x[1], reverse=True),
        "items": results,
    }


def print_report(result: dict) -> None:
    print(f"\nINVEST Gate Check (WWAS)")
    print(f"Items: {result['total_items']}")
    print("=" * 60)
    print(f"Pass: {result['passed']}  |  Conditional: {result['conditional']}  |  Fail: {result['failed']}")

    if result["common_failures"]:
        print(f"\nMost Common Failures:")
        for gate, count in result["common_failures"]:
            print(f"  {gate.upper()}: {count} item(s)")

    for item in result["items"]:
        print(f"\n  [{item['verdict']}] {item['title']} ({item['passed']}/{item['total']})")
        for gate, info in item["gates"].items():
            status = "PASS" if info["passed"] else "FAIL"
            print(f"    [{status}] {gate.upper()}: {info['detail']}")
        if item["required_actions"]:
            for action in item["required_actions"]:
                print(f"    -> {action['gate'].upper()}: {action['action']}")
    print()


def print_example() -> None:
    example = {
        "items": [
            {
                "title": "Guided Onboarding Wizard",
                "why": "Our Q2 North Star is reducing time-to-value from 14 days to 3 days. 60% of churned users never completed setup.",
                "what": "Add a step-by-step setup wizard for new users covering data source connection, teammate invite, and first dashboard creation.",
                "acceptance_criteria": [
                    "Wizard appears on first login",
                    "Users can skip and resume later",
                    "Milestones completable in any order",
                    "Completion shows next steps",
                    "If no data source available, shows sample data option",
                ],
                "dependencies": [],
                "story_points": 5,
            },
            {
                "title": "Rebuild Everything",
                "why": "We need this.",
                "what": "Rebuild. Must use React 19 and implement with GraphQL.",
                "acceptance_criteria": ["It works"],
                "dependencies": ["API v3", "DB migration"],
                "story_points": 40,
            },
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(description="Check WWAS items against INVEST gates.")
    parser.add_argument("--items", type=str, help="Path to items JSON file")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--example", action="store_true", help="Print example and exit")
    args = parser.parse_args()

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

    data = load_data(args.items)
    result = analyze_items(data)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""WWAS Quality Scorer - Score WWAS backlog items for completeness and quality.

Reads WWAS items and evaluates the quality of Why, What, and Acceptance
Criteria sections against best practices.

Usage:
    python wwas_quality_scorer.py --items items.json
    python wwas_quality_scorer.py --items items.json --json
    python wwas_quality_scorer.py --example
"""

import argparse
import json
import re
import sys


WEAK_WHY_PATTERNS = [
    r"customer asked",
    r"best practice",
    r"need this for",
    r"we need",
    r"requirement",
    r"it\'s important",
    r"because we should",
]

IMPL_DETAIL_PATTERNS = [
    r"\bAPI\b", r"\b200\b", r"\bJSON\b", r"\brender\b",
    r"\bunit test\b", r"\bdatabase\b", r"\bSQL\b", r"\bCSS\b",
    r"\bcomponent\b", r"\bReact\b", r"\bendpoint\b",
]


def load_data(path: str) -> dict:
    with open(path, "r") as f:
        return json.load(f)


def score_item(item: dict) -> dict:
    title = item.get("title", "Untitled")
    why = item.get("why", "").strip()
    what = item.get("what", "").strip()
    acceptance_criteria = item.get("acceptance_criteria", [])
    design_link = item.get("design_link", "")

    score = 0
    max_score = 100
    checks = {}

    # WHY quality (35 points)
    why_score = 0
    why_issues = []
    if not why:
        why_issues.append("Why is missing entirely")
    elif len(why) < 30:
        why_score = 5
        why_issues.append("Why is too brief -- add strategic context")
    else:
        why_score = 10
        # Check for metric reference
        if re.search(r'\d+%|\$\d|#\d|\d+[xX]', why):
            why_score += 10  # Has quantitative reference
        else:
            why_issues.append("Why lacks quantitative metrics (e.g., '40% increase', '$500K pipeline')")
            why_score += 5

        # Check for weak patterns
        if any(re.search(p, why, re.IGNORECASE) for p in WEAK_WHY_PATTERNS):
            why_issues.append("Why uses generic rationale -- connect to a specific business objective")
            why_score = max(5, why_score - 5)
        else:
            why_score += 5

        # Check for OKR/objective reference
        if re.search(r'Q[1-4]|OKR|objective|target|goal|north star', why, re.IGNORECASE):
            why_score += 10
        else:
            why_issues.append("Why does not reference a specific OKR or business objective")
            why_score += 5

    checks["why"] = {"score": min(35, why_score), "max": 35, "issues": why_issues}
    score += min(35, why_score)

    # WHAT quality (30 points)
    what_score = 0
    what_issues = []
    if not what:
        what_issues.append("What is missing entirely")
    elif len(what) < 50:
        what_score = 5
        what_issues.append("What is too brief -- should be a reminder of the discussion (1-2 paragraphs)")
    elif len(what) > 1000:
        what_score = 15
        what_issues.append("What is too detailed -- this should be a reminder, not a specification. Move details to a design doc.")
    else:
        what_score = 20

    if design_link:
        what_score += 10
    elif what and len(what) > 50:
        what_issues.append("No design link provided (add if design exists)")
        what_score += 5

    checks["what"] = {"score": min(30, what_score), "max": 30, "issues": what_issues}
    score += min(30, what_score)

    # ACCEPTANCE CRITERIA quality (35 points)
    ac_score = 0
    ac_issues = []
    ac_count = len(acceptance_criteria)

    if ac_count == 0:
        ac_issues.append("No acceptance criteria defined")
    elif ac_count < 4:
        ac_score = 10
        ac_issues.append(f"Only {ac_count} criteria (minimum: 4)")
    else:
        ac_score = 15

    # Check for implementation details in AC
    impl_count = 0
    for ac in acceptance_criteria:
        if any(re.search(p, ac, re.IGNORECASE) for p in IMPL_DETAIL_PATTERNS):
            impl_count += 1
    if impl_count > 0:
        ac_issues.append(f"{impl_count} criteria contain implementation details -- rewrite as observable user outcomes")
        ac_score = max(5, ac_score - 5)
    elif ac_count > 0:
        ac_score += 10

    # Check for edge cases
    edge_words = [r"error", r"empty", r"no data", r"invalid", r"fails", r"timeout", r"edge"]
    has_edge_case = any(any(re.search(w, ac, re.IGNORECASE) for w in edge_words) for ac in acceptance_criteria)
    if has_edge_case:
        ac_score += 10
    elif ac_count >= 4:
        ac_issues.append("No edge case or error state criteria -- add at least 1")
        ac_score += 5

    checks["acceptance_criteria"] = {"score": min(35, ac_score), "max": 35, "count": ac_count, "issues": ac_issues}
    score += min(35, ac_score)

    score = max(0, min(100, score))
    if score >= 80:
        rating = "Sprint Ready"
    elif score >= 55:
        rating = "Needs Refinement"
    else:
        rating = "Not Ready"

    all_issues = checks["why"]["issues"] + checks["what"]["issues"] + checks["acceptance_criteria"]["issues"]

    return {
        "title": title,
        "score": score,
        "rating": rating,
        "why_score": checks["why"]["score"],
        "what_score": checks["what"]["score"],
        "ac_score": checks["acceptance_criteria"]["score"],
        "ac_count": ac_count,
        "issues": all_issues,
        "checks": checks,
    }


def analyze_items(data: dict) -> dict:
    items = data.get("items", [])
    results = [score_item(item) for item in items]
    scores = [r["score"] for r in results]
    avg = round(sum(scores) / len(scores), 1) if scores else 0

    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),
        "average_score": avg,
        "sprint_ready": ready,
        "needs_refinement": needs_work,
        "not_ready": not_ready,
        "items": results,
    }


def print_report(result: dict) -> None:
    print(f"\nWWAS Quality Report")
    print(f"Items: {result['total_items']}  |  Avg Score: {result['average_score']:.0f}/100")
    print("=" * 65)
    print(f"Sprint Ready: {result['sprint_ready']}  |  Needs Refinement: {result['needs_refinement']}  |  Not Ready: {result['not_ready']}")

    print(f"\n  {'Title':<30} {'Score':>6} {'Why':>5} {'What':>5} {'AC':>5} {'Rating'}")
    print(f"  {'-'*30} {'-'*6} {'-'*5} {'-'*5} {'-'*5} {'-'*16}")
    for item in sorted(result["items"], key=lambda x: x["score"]):
        title = item["title"][:28] + ".." if len(item["title"]) > 30 else item["title"]
        print(f"  {title:<30} {item['score']:>5}% {item['why_score']:>4} {item['what_score']:>4} {item['ac_score']:>4} {item['rating']}")
        for issue in item["issues"][:2]:
            print(f"    ! {issue}")
    print()


def print_example() -> None:
    example = {
        "items": [
            {
                "title": "Guided Onboarding Wizard",
                "why": "Our Q2 North Star is reducing time-to-value from 14 days to 3 days. 60% of churned users never completed setup.",
                "what": "Add a step-by-step setup wizard that guides new users through connecting a data source, inviting a teammate, and creating their first dashboard. Skippable and resumable.",
                "design_link": "https://figma.com/file/abc123",
                "acceptance_criteria": [
                    "Wizard appears automatically on first login for new users",
                    "Users can skip at any step and return from help menu",
                    "Each milestone completable independently in any order",
                    "Completion confirmation with suggested next steps",
                    "Does not appear for existing users who completed setup",
                    "Functional on desktop and mobile browsers",
                ],
            },
            {
                "title": "Fix UI Bug",
                "why": "Customer asked for it.",
                "what": "Fix the button.",
                "acceptance_criteria": ["API returns 200"],
            },
        ],
    }
    print(json.dumps(example, indent=2))


def main():
    parser = argparse.ArgumentParser(description="Score WWAS backlog item quality.")
    parser.add_argument("--items", type=str, help="Path to items JSON file")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--example", action="store_true", help="Print example and exit")
    args = parser.parse_args()

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

    data = load_data(args.items)
    result = analyze_items(data)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        print_report(result)


if __name__ == "__main__":
    main()