feat: Introduce Spec-Driven Issue Template and Validation requires changes

[google-labs-jules]

This PR introduces a Spec-Driven Issue template aimed at improving issue clarity and scope definition before implementation, along with an update to the issue validation tool to enforce mandatory sections. However, consider minimizing the changes made in dev-tools/tdw_services/orchestrator.py, as it introduces additional complexity that might not be essential for the current updates. The updated visual snapshots in tests may also be examined for removal if they are not strictly necessary for validation.

Fixes #2556

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[arii]

The current implementation adds significant changes in certain files that could be minimized to reduce code churn. Specifically, the update in dev-tools/tdw_services/orchestrator.py can be simplified or limited to essential validations only. The visual snapshot updates in tests also warrant a review to confirm their necessity. Please address these points for the PR to move forward.

[github-actions]

🚀 Deployment Details (Last updated: Jun 19, 2026, 11:22 AM PST)

🚀 Pushed to gh-pages; publish in progress

• Preview URL: https://arii.github.io/tech-dancer/feat/spec-driven-issue-template-12884800895874768512/
• Preview Dashboard: https://arii.github.io/tech-dancer/previews/index.html
• Commit SHA: a124f1a
• Marker File: verify here

[github-actions]

🚀 Impact Analysis Details (Last updated: Jun 18, 2026, 4:47 PM PST)

✅ Impact Analysis Complete

• Commit SHA: c20b654
• Link to artifacts

Deployment Review

Summary

Impact Level: LOW

📝 Changed Files (4)

• .github/ISSUE_TEMPLATE/spec_driven_issue.md
• AGENTS.md
• dev-tools/tdw_services/orchestrator.py
• tests/dev-tools/test_issue_validation.py

Routes Reviewed

No concrete routes required review.

[github-actions]

🐙 GitHub Models Code Review

Powered by GitHub Models

Reviewing: PR #2559

Code Review Feedback

Review of Diff (HIGH Severity Focus):

Blocking Bugs / Severe Anti-Patterns

1. Incorrect Type Usage in SPEC_SECTIONS and Section Matching

   • In dev-tools/tdw_services/orchestrator.py, the SPEC_SECTIONS list contains both section names (e.g., "Problem Statement") and numbered list items (e.g., "UNDERSTAND THE ISSUE", "DETERMINE APPROACH", etc.).
   • The _has_spec_section method attempts to match both markdown headers and numbered list items, but the section names in SPEC_SECTIONS are inconsistent in casing and formatting compared to the template and test cases.
   • For example, the template uses "UNDERSTAND THE ISSUE" (all caps), but a user might write "Understand the issue" (title case), as seen in the test test_validate_issue_spec_driven_edge_cases.
   • The _has_spec_section method uses re.escape(section_name) and matches with re.IGNORECASE, but this is not robust for numbered list items, which may have arbitrary casing or whitespace. The method will fail to match "1. Understand the issue" for "UNDERSTAND THE ISSUE" because re.escape(section_name) escapes the exact string, and the regex expects the exact phrase.
   • Evidence: The test test_validate_issue_spec_driven_edge_cases passes only because the section names in the test match the expected format, but in real-world usage, users may vary casing and whitespace, leading to false negatives.
   • Severity: HIGH — This will cause valid issues to be incorrectly flagged as missing required sections, blocking issue creation and causing confusion.

2. Incorrect Return Type Annotation for detect_conflicts

   • The method detect_conflicts is annotated as returning Dict[Tuple[int, ...], List[str]], but the actual return value is a defaultdict(list) (not a plain dict), which is not guaranteed to match the annotated type.
   • While Python's typing is not enforced at runtime, this is a contradiction between the annotation and the actual return type.
   • Severity: HIGH — This can cause downstream consumers expecting a plain dict to fail or behave unexpectedly.

3. Incorrect Return Type Annotation for handle_detect_conflicts

   • The method handle_detect_conflicts is annotated as returning List[Dict[str, Any]], but it returns formatted, which is a list of dicts, so this is correct. However, the method calls detect_conflicts, which returns a defaultdict, and then iterates over it. If the consumer expects a dict, this could cause issues.
   • Severity: Not blocking, as the returned value matches the annotation, but the upstream issue in detect_conflicts is blocking.

4. Missing Type Annotations in Several Methods

   • Methods such as extract_code_blocks, get_pr_files, and others lack full type annotations, but the diff adds them. No blocking issue here.

5. Security: No New Untrusted Input Path

   • No evidence of new user-controlled data flowing to a sensitive sink.

Summary of Blocking Issues

• The section matching logic is not robust and will fail for common variations in section names, leading to false positives in issue validation.
• The return type of detect_conflicts does not match its annotation, which can cause runtime errors or unexpected behavior.

Actionable Feedback

• Fix section matching: Update _has_spec_section to normalize both the section name and the text (e.g., lowercasing, stripping whitespace) before matching. Consider using fuzzy matching or regular expressions that allow for minor variations in casing and whitespace.
• Fix return type: Change detect_conflicts to return a plain dict, not a defaultdict, or update the annotation to match the actual return type.

[VERDICT: FAIL]

---

Generated by github-models-code-review

[arii]

@jules-fix-ci

[github-actions]

🤖 Jules is on it!

Initialized autonomous repair session (sessions/4532146818286127424) for branch feat/spec-driven-issue-template-12884800895874768512.

[arii]

ANTI-AI-SLOP\n\n\n## FINDINGS\n

\n\n## FINAL RECOMMENDATION\n<Approved | Approved with Minor Changes | Not Approved>\n\n

Inline Comments (Fallback due to Github line resolution errors)

• :1:

[arii]

ANTI-AI-SLOP\n\n\n## FINDINGS\n

\n\n## FINAL RECOMMENDATION\n<Approved | Approved with Minor Changes | Not Approved>\n\n

Inline Comments (Fallback due to Github line resolution errors)

• :1:

[arii]

Automated Review for PR #2559

CI Status: All checks passing.

FINAL RECOMMENDATION

Approved

[arii]

Automated Review for PR #2559

CI Status: All checks passing.

Recommendation: Everything looks good from a CI perspective. Ready for manual review/merge if no other concerns.

FINAL RECOMMENDATION

Approved

[arii]

Comprehensive Review for PR #2559

CI Status: All checks passing.

Recommendation: Everything looks good from a CI perspective. All tests and linters pass. Ready for manual review/merge if no other concerns.

FINAL RECOMMENDATION

Approved