oss-issue-strict

name	oss-issue-strict
description	Use when contributing GitHub issue fixes that must match local code style, avoid AI-like over-engineering, run internal review loops, and block PR creation until all must-fix findings are resolved or explicitly waived.

OSS Issue Strict

Purpose

Deliver issue fixes with minimal diff, local style matching, and hard quality gates so work is PR-ready without churn.

Core Principles

• Minimal diff first: change only what is needed to satisfy the issue contract.
• Match local style: mirror naming, control flow, test patterns, and file organization in the touched area.
• Reuse existing helpers and abstractions before creating new ones.
• No scope creep: avoid unrelated cleanups, refactors, or speculative improvements.
• No speculative abstractions: do not add generic layers for hypothetical future cases.
• Reason privately, decide explicitly: think step by step internally, but output only concise decisions and evidence.
• Evidence over intuition: every non-trivial change must map to a failing test, acceptance criterion, or explicit reviewer finding.

Non-Negotiables

• Reuse in-repo primitives/helpers unless technically impossible.
• Keep behavior and API surface stable unless the issue explicitly requires changes.
• Prefer targeted tests over broad rewrites.
• Do not open a PR path while unresolved must-fix findings exist unless explicitly waived through /oss-force-pr.

AI Best Practices (Execution Protocol)

1. Contract before code
   • Restate the issue as testable acceptance criteria and non-goals before editing files.
2. Plan in micro-steps
   • Break work into small hypotheses and apply one behavior change at a time.
3. Prove before and after
   • Capture baseline failure, apply minimal fix, then prove with targeted tests and relevant project checks.
4. Use evidence-bound reasoning
   • Tie each decision to repo evidence: nearby patterns, existing helper behavior, or failing output.
5. Run adversarial self-review
   • Before declaring done, challenge the patch for over-engineering, style drift, hidden side effects, and scope creep.
6. Prefer stable deterministic paths
   • Avoid nondeterministic fixes, broad refactors, and large rewrites when a focused patch is sufficient.
7. Keep communication concise
   • Summarize what changed, why it is correct, and what was intentionally left untouched.

Workflow

1. Intake and contract
   • Parse issue URL/number and gather acceptance criteria, constraints, and out-of-scope boundaries.
   • Produce a concrete issue contract before coding.
2. Style calibration
   • Inspect nearby files/tests and extract local style rules to follow.
3. TDD minimal implementation
   • Write or update failing tests for required behavior.
   • Implement the smallest fix that makes tests pass.
4. Internal review swarm
   • Run three review perspectives: spec/scope, style consistency, quality/paranoia.
5. Adjudication
   • Classify each finding as must-fix, optional, or ignore.
6. Auto loop (max 2 rounds in lite mode, max 3 in strict mode) with redundancy shield
   • Address must-fix findings.
   • Re-run validations and review swarm.
   • Fingerprint findings and ignore duplicates/reworded repeats already handled or explicitly dispositioned.
7. Fail-closed gate
   • If any must-fix remains unresolved after loop, stop in blocked state.
8. PR package
   • If unblocked, generate a PR-ready package and wait for explicit user confirmation before any gh pr create.

Redundancy Shield

• Fingerprint each finding by normalized tuple:
  • category
  • impacted file/symbol
  • underlying rule violated
  • required action
• Deduplicate within and across rounds.
• When reworded duplicates appear, map to existing fingerprint and keep prior disposition.

Override Policy (/oss-force-pr)

• Break-glass only.
• Requires explicit override reason and full visibility of unresolved blockers.
• Requires explicit confirmation phrase FORCE_PR_ACK.
• Must include waiver details in PR package: unresolved blockers, why not fixed now, and risk ownership.
• Even with waiver, still require explicit user confirmation before running gh pr create.

Output Contract

Always produce:

1. Issue contract
   • Problem statement, acceptance criteria, constraints, non-goals.
2. Changed files
   • File list with one-line rationale per file.
3. Validation report
   • Commands run and pass/fail status.
4. Review disposition
   • Findings grouped as must-fix/optional/ignore with fingerprint IDs and resolution status.
5. Final state
   • Either:
     • PR draft package ready for user approval, or
     • Blocked state with unresolved must-fix items and next required actions.