loop-engineering
Execute non-trivial software work through small, observable build-test-observe-adjust loops with explicit hypotheses, evidence, outcomes, and next actions. Use throughout feature implementation, debugging, refactoring, migrations, performance work, and complex verification where feedback must guide each subsequent step. Use when work is stalling, changes are growing too large, failures repeat, or an engineering ledger is required.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- loop-engineering
- description
- Execute non-trivial software work through small, observable build-test-observe-adjust loops with explicit hypotheses, evidence, outcomes, and next actions. Use throughout feature implementation, debugging, refactoring, migrations, performance work, and complex verification where feedback must guide each subsequent step. Use when work is stalling, changes are growing too large, failures repeat, or an engineering ledger is required.
02 资源文件 3
- 参考文档agents/openai.yaml328 B
- 参考文档references/loop-recovery.md2.3 KB
- 参考文档references/suite-contract.md2.1 KB
03 SKILL.md 正文
Loop Engineering
Mission
Own execution cadence and learning. Keep each loop small, observable, reversible with precise edits, and driven by evidence.
Do not own detailed test method, architecture policy, or final approval. Route behavior changes to test-driven-development, structural decisions to solid-design, and completion to quality-gates through the orchestrator.
Suite Protocol
When another skill routes work here, read references/suite-contract.md. Accept the Task Packet and return the standard Handoff Packet. Each loop adds evidence and a next action; it does not independently declare the overall task complete.
Open a Loop
Define:
Loop: <number or short ID>
Hypothesis: <what this step should prove or change>
Scope: <one behavior, diagnostic, or structural move>
Evidence plan: <test, inspection, metric, build, or runtime signal>
Stop condition: <observable success, failure, or split threshold>
Reject a loop that contains several independently verifiable outcomes. Split by behavior, dependency, caller group, migration batch, or risk.
Run the Cycle
1. Observe
Inspect current code, tests, logs, runtime behavior, metrics, or errors. Separate known baseline failures from new failures. Never begin from an assumed state.
2. Frame
Choose the smallest uncertainty or behavior that blocks progress. State a falsifiable hypothesis and the evidence needed to decide.
3. Execute
- For new behavior or a defect, invoke
test-driven-developmentand complete one valid Red–Green–Refactor cycle. - For a structural move, obtain a boundary decision from
solid-design, preserve behavior with tests, and move one responsibility, dependency, contract, or caller group. - For diagnosis, change one variable or add one observation point. Do not mix diagnosis with a broad fix.
- For bulk work, run one representative or low-risk batch before scaling.
4. Measure
Run the focused evidence check, then proportionate broader checks. Capture actual output, not memory or expectation.
5. Compare
Classify the loop:
- Confirmed: Evidence matches the hypothesis and acceptance behavior.
- Refuted: Evidence disproves the hypothesis.
- Inconclusive: The observation cannot distinguish causes.
- Blocked: A missing dependency, permission, decision, or broken baseline prevents a valid result.
6. Adjust
Choose exactly one next action:
- Advance to the next behavior or structural move.
- Tighten the test or observation.
- Reduce the scope.
- Return to architecture shaping.
- Repair the baseline or environment.
- Escalate a material user decision.
- Stop because acceptance is satisfied or the work is blocked.
Do not stack speculative fixes after a refuted or inconclusive loop.
Keep the Ledger
Use an existing build log, engineering diary, task record, or project journal. If none exists, retain a concise ledger for the final report:
| Loop | Hypothesis | Action | Evidence | Outcome | Next |
|---|
Record exact commands and meaningful results. Do not dump noisy logs when a precise summary and failure excerpt are sufficient.
For long-running work, send the user brief progress updates at meaningful loop boundaries without turning the ledger into play-by-play commentary.
Control Loop Size
Split the loop when:
- More than one acceptance behavior is changing.
- Several production modules must change for unrelated reasons.
- A test failure has more than one plausible cause.
- Review becomes difficult because the diff mixes behavior and structure.
- A migration batch cannot be independently verified or rolled back.
- The success condition cannot be stated in one sentence.
One loop may touch multiple files when they form one atomic behavior or contract change. File count alone does not define loop size.
Recover from Failure
Read references/loop-recovery.md when loops repeat, focused checks pass but broader checks fail, the environment is unreliable, or the next action is unclear.
Use precise patches to remove only the failed experiment's changes. Preserve unrelated user work. Never use destructive resets as a loop shortcut.
Stop Correctly
Stop iteration when one condition holds:
- Requested acceptance behavior is satisfied and evidence is ready for
quality-gates. - A material decision or new authority is required from the user.
- The environment cannot produce trustworthy evidence.
- Continuing would expand scope beyond the request.
Do not stop merely because the first plausible implementation compiles or one focused test passes.
Return the Handoff
Return to the orchestrator:
Completed loops: <IDs and outcomes>
Acceptance status: <satisfied | partial | blocked>
Focused evidence: <results>
Broader observation: <results>
Architecture questions: <none or route to SOLID>
Residual risk: <specific gap>
Recommended next phase: <shape | red | observe | gate | blocked>
04 同仓库更多 Skills
test-driven-development
Drive one observable software behavior at a time through a valid Test-Driven Development cycle: select the test, prove Red for the intended reason, implement the smallest Green change, and preserve the test as regression evidence. Use before adding production behavior, fixing defects, changing contracts, or safely characterizing legacy behavior. Also use when tests are brittle, over-mocked, skipped, weakened, or passing without proving the requirement.
suite-orchestrator
Route complex work across the complete Agent Skill Suite while enforcing content preservation, explicit scope, correct specialist timing, evidence-backed completion, and durable state. Use when a task involves coding, agent operations, repository bootstrapping, conversation compilation, artifact generation, expert review, persistent memory, or several of these together. Also use when the correct skill is unclear or work must pass through multiple specialist skills in a controlled sequence.
solid-design
Design, refactor, and review object-oriented or modular code with the SOLID principles while preserving behavior and avoiding needless abstraction. Use when defining responsibilities, extension seams, subtype contracts, consumer interfaces, dependency direction, modules, services, strategies, plugins, adapters, repositories, or architecture boundaries; also use when test friction, tangled dependencies, large classes, unsupported methods, framework leakage, or repeated variant branches signal a structural problem.
quality-gates
Verify engineering work against required behavioral, architectural, regression, build, security, compatibility, documentation, and diff-hygiene evidence before completion. Use after a code change, defect fix, refactor, migration, generated-code update, or implementation plan appears complete; also use for read-only code reviews and release-readiness checks. Return PASS or BLOCKED without implementing the remediation.
local-memory
Maintain fast, durable, curated local memory for AI agents on Android, Termux, Linux, macOS, Windows, or other lightweight environments. Use when an agent must remember stable preferences, project facts, decisions, procedures, failure resolutions, and task state across sessions; retrieve relevant memories before planning; resolve conflicting or stale memories; or provide explicit remember, search, pin, update, forget, status, and export controls without a cloud dependency.
implementation-council
Pressure-test codebases, specifications, architecture notes, implementation plans, test strategies, migrations, and deployment plans through a structured council of fixed engineering leaders and task-specific specialists. Use when the user requests an expert panel, adversarial review, debate, gap analysis, implementation improvement, production-readiness assessment, or deployment verdict. Require evidence, disagreement, rebuttal, prioritized gaps, and a clear readiness decision.