Specloop

SpecLoop

Deliver a software change through a controlled loop:

DISCOVER -> SPEC -> BUILD -> REVIEW -> REPAIR -> REVIEW

Continue until all hard gates pass or the task is honestly blocked.

This skill is self-contained. If compatible spec, build, or review skills are available, they may be used for the matching phase only when they follow the same approved specification, artifact paths, and gates. Never depend on nested slash-command support.

Compatibility

Requires a coding agent that can read and write project files and run available verification commands. Designed for Agent Skills-compatible clients; nested skill invocation is optional, not required.

Core invariants

1. The approved specification is the source of truth.
2. Never change the specification merely to make the implementation pass.
3. Never invent product requirements or silently expand scope.
4. Never weaken, remove, skip, or falsify tests or checks to obtain PASS.
5. Never claim PASS without direct evidence from the current project state.
6. Preserve existing behavior outside the approved scope.
7. Preserve unrelated user changes. Do not reset, discard, overwrite, or hide them.
8. Do not deploy, publish, push, merge, commit, mutate production data, or call destructive external actions unless the user explicitly authorized that action.
9. Do not loop forever. Stop under the blocking rules.
10. Higher-priority user, host, safety, and repository instructions override this skill.

Operating modes

Infer the mode from the user request.

Interactive mode

Use when material product decisions are missing or the user asks to approve the plan.

Ask one focused question at a time. Pause before BUILD until the specification is approved.

Autonomous mode

Use when the user explicitly asks for end-to-end delivery, automatic repair, or work until PASS.

Proceed without routine approval after writing the specification. Resolve non-material ambiguity with conservative assumptions and record them. Pause only when a missing decision materially changes behavior, scope, safety, data handling, external systems, or irreversible actions.

The user's request for autonomous execution is not authorization for destructive or external side effects.

Resume mode

If artifacts already exist, read them first and resume from the recorded phase. Do not restart completed work without reason.

Defaults

Unless the user specifies otherwise:

• Spec: specs/<task-slug>.md
• Review: specs/<task-slug>.review.md
• Loop state: specs/<task-slug>.loop.md
• Evidence: specs/<task-slug>.evidence.md
• Minimum review score: 9.5/10
• Maximum repair iterations: 6

Prefer a user-supplied spec path. Otherwise reuse a clearly matching existing spec before creating a new one.

Phase 0: DISCOVER

Before writing or changing code:

1. Determine the workspace or repository root.
2. Inspect the current state and identify pre-existing changes.
3. Read applicable instructions and conventions, including relevant repository guidance, README files, contribution docs, manifests, lockfiles, build files, test configuration, and CI definitions.
4. Respect the most specific applicable repository instructions.
5. Identify the project type, package or build system, runtime, test framework, and available tools from evidence. Do not guess commands when the project declares them.
6. Inspect the relevant implementation and architecture before proposing changes.
7. Discover verification commands and classify each as:
   • REQUIRED: explicitly required by the user, approved spec, repository instructions, release policy, or a directly affected project gate.
   • RELEVANT: useful confidence-building validation but not a hard project gate.
   • UNAVAILABLE: cannot run in the current environment.
8. Create a check plan. Every requirement must have at least one verification method, which may be automated, runtime, manual, or static. Label the method honestly.
9. Record the baseline revision and diff when version control is available. If not, record the initial file state as well as the environment permits.

Do not modify unrelated files merely to make the repository cleaner.

Phase 1: SPEC

If a matching specification exists, read it completely and verify that it matches the user's current request.

Otherwise create a specification that contains:

• Objective
• Current behavior
• Desired behavior
• In scope
• Out of scope
• Assumptions
• Numbered functional requirements: R1, R2, ...
• Non-functional requirements when applicable
• Constraints
• Compatibility and migration requirements when applicable
• Security and privacy requirements when applicable
• Edge cases and failure behavior
• Acceptance criteria linked to requirement IDs
• Required check plan
• Definition of done

Rules:

1. Ask only questions that are material to a correct implementation.
2. In interactive mode, ask one focused question at a time.
3. In autonomous mode, document conservative assumptions instead of asking about non-material details.
4. Use stable requirement IDs. Never renumber existing IDs during repair.
5. Mark omitted ideas as out of scope rather than silently implementing them.
6. Save the specification before BUILD.
7. Record a spec version or fingerprint in the loop state. Any later spec change invalidates previous review results.
8. If the implementation reveals a real spec gap, report SPEC GAP; do not rewrite the spec without user approval unless the change is a non-behavioral clarification.

Phase 2: BUILD

Implement the approved specification exactly.

1. Re-read the complete spec and applicable project instructions.
2. Map each requirement to intended code and verification before editing.
3. Make the smallest coherent change that satisfies the approved scope.
4. Refactor only when directly required for correctness, safety, or maintainability of the requested change. Explain any such refactor.
5. Add or update tests for changed behavior when a test framework exists and the behavior is testable.
6. Do not replace meaningful assertions with weaker ones.
7. Do not delete failing tests unless the approved specification explicitly makes them obsolete; document the reason and replacement coverage.
8. Handle migrations, compatibility, rollback, and data integrity when the change affects persisted data or public contracts.
9. Run affected checks during implementation.
10. Write evidence that maps every requirement to:
    • Files or components changed
    • Implementation evidence
    • Verification method
    • Command and exit result when applicable
    • Remaining uncertainty

If no code change is needed, prove why the existing implementation already satisfies the spec.

Phase 3: REVIEW

Review the actual project state, not the builder's summary.

Use the strongest available reviewer isolation:

1. Separate reviewer agent or subagent
2. Fresh review context
3. Strict self-review after re-reading the spec and diff from disk

Record which isolation level was used. Do not claim independent review when the same agent performed it.

The reviewer must not modify implementation code during the review phase.

Review all of the following:

• Every requirement and acceptance criterion
• Complete relevant diff against the recorded baseline
• Required and relevant check results
• Runtime behavior where applicable
• Edge cases and failure paths
• Security, privacy, permissions, secrets, and data integrity proportional to the change
• Compatibility, migration, and rollback risks when applicable
• Regressions and unexplained out-of-scope changes
• Documentation and operability when needed

For each requirement, record exactly one status:

• PASS
• FAIL
• BLOCKED
• NOT APPLICABLE only when the spec explicitly permits it

For every non-PASS result include:

• Requirement or acceptance criterion ID
• Severity
• Exact gap
• Evidence
• Required fix or external action
• Verification needed to close it

Severity

• CRITICAL: exploitable security issue, irreversible data loss, unsafe operation, or system-wide failure.
• HIGH: required behavior is broken, a required check fails, a major regression exists, or authorization/data integrity is materially wrong.
• MEDIUM: partial behavior, meaningful edge-case gap, insufficient verification, or maintainability risk that does not break a hard requirement.
• LOW: minor defect or documentation/operability issue with limited impact.

Hard gates

Final PASS requires every line below to be true:

ALL REQUIREMENTS PASS
ALL ACCEPTANCE CRITERIA PASS
ALL REQUIRED CHECKS PASS
EVIDENCE COMPLETE
NO UNRESOLVED BLOCKERS
NO CRITICAL OR HIGH FINDINGS
NO KNOWN FUNCTIONAL REGRESSIONS
NO UNAPPROVED SCOPE CHANGES
NO UNEXPLAINED OUT-OF-SCOPE CHANGES
REVIEW SCORE >= 9.5/10

A score never overrides a failed hard gate. If any hard gate fails, the score cannot exceed 9.4/10 and the verdict cannot be PASS.

Review score

Score only from evidence:

Category	Weight
Requirements and acceptance criteria	40%
Correctness and edge cases	20%
Verification quality	15%
Security, reliability, and data integrity	10%
Regression safety and scope discipline	10%
Documentation and operability	5%

Use:

score = 10 * earned applicable points / maximum applicable points

A category may be excluded only with an explicit reason and evidence that it is genuinely not applicable. Requirements, correctness, verification, and scope discipline are always applicable.

Save the full report to the review path.

Phase 4: REPAIR LOOP

When REVIEW returns FAIL:

1. Read the current spec, review report, evidence, and loop state.
2. Convert every unresolved finding into a repair item with a stable finding ID.
3. Fix failed items and their direct consequences only.
4. Add regression coverage where practical.
5. Re-run affected checks.
6. Re-run the complete review against all requirements, not only repaired items.
7. Confirm that a repair did not reopen a previously passing item.
8. Append the iteration result to the loop state.
9. Repeat until PASS or BLOCKED.

A finding closes only after its required verification passes. A code change alone is not closure.

Track at least:

• Current phase
• Spec version or fingerprint
• Iteration number
• Baseline revision
• Findings opened and closed
• Checks run with outcomes
• Score before and after repair
• Remaining blockers
• Final verdict

Required-check policy

1. A failed REQUIRED check is a hard failure.
2. An unavailable REQUIRED check is BLOCKED unless an approved equivalent verification exists.
3. An unavailable RELEVANT check does not automatically block PASS, but it must be disclosed and reflected in the evidence and score.
4. Never silently downgrade a required check to relevant.
5. Do not treat a command as passing unless it completed successfully and its result was inspected.
6. Do not claim an automated test passed when only static or manual inspection was performed.

Blocking rules

Return SPECLOOP BLOCKED when any of these applies:

• Maximum repair iterations are reached
• The same finding persists through two repair attempts without measurable progress
• Repairs oscillate by reopening previously closed findings
• Required credentials, permissions, infrastructure, services, data, or tools are unavailable
• A required check cannot run and has no approved equivalent
• Requirements conflict or a material product decision is missing
• A destructive, irreversible, production, deploy, publish, merge, or external mutation requires authorization
• The approved specification must change materially
• The environment cannot read, modify, or verify the project sufficiently

When blocked, report:

• Exact blocker
• Affected requirement and finding IDs
• Evidence
• Work completed
• What remains unverified
• Exact user or external action required
• Safest next step

Do not present partial completion as PASS.

Final output

Return SPECLOOP PASS only when every hard gate passes.

SPECLOOP PASS

SPEC: <path>
SPEC VERSION: <version-or-fingerprint>
ITERATIONS: <number>
REVIEWER ISOLATION: <level>
REVIEW SCORE: <score>/10

ALL REQUIREMENTS PASS
ALL ACCEPTANCE CRITERIA PASS
ALL REQUIRED CHECKS PASS
EVIDENCE COMPLETE
NO UNRESOLVED BLOCKERS
NO CRITICAL OR HIGH FINDINGS
NO KNOWN FUNCTIONAL REGRESSIONS
NO UNAPPROVED SCOPE CHANGES
NO UNEXPLAINED OUT-OF-SCOPE CHANGES

CHECKS:
- <command or verification>: PASS

ARTIFACTS:
- <spec path>
- <review path>
- <evidence path>
- <loop state path>

Otherwise return exactly one of:

SPECLOOP FAIL

SPECLOOP BLOCKED

Never replace these verdicts with optimistic wording.