nav-loop_skill

Overview

This skill runs tasks iteratively until they meet structured completion signals, preventing premature stops and endless loops. It provides phased progress (INIT → RESEARCH → IMPL → VERIFY → COMPLETE), stagnation detection, and a dual-condition exit gate that combines heuristics with an explicit EXIT_SIGNAL. It’s designed to extend session longevity and finish multi-step developer tasks autonomously.

How this skill works

On activation, the loop initializes state from configuration and starts iterations that perform work according to the current phase. After each iteration it emits a NAVIGATOR_STATUS block with phase, indicators, state hash, and next action. The skill detects stagnation via repeated state hashes, presents recovery choices, and evaluates a dual-condition exit gate requiring heuristics plus an optional explicit EXIT_SIGNAL. Max iterations and thresholds prevent runaway loops.

When to use it

• When the user says 'run until done', 'keep going until complete', 'iterate until finished', or 'loop mode'.
• For multi-step engineering tasks that need repeated implement/verify cycles (features, bug fixes, refactors).
• When you want clear iteration visibility and automatic commit/test/simplify steps.
• To recover from repeated failed attempts via stagnation detection and guided recovery.
• Not for single-step tasks, exploratory sessions without clear exit criteria, or when loop mode is explicitly disabled.

Best practices

• Enable loop mode for tasks with measurable completion indicators (commits, tests, docs).
• Configure sensible max_iterations (1–20) and stagnation_threshold (2–5) in .nav-config.json.
• Require EXIT_SIGNAL when human confirmation is needed to avoid premature exits.
• Use status blocks to review progress each iteration and decide on Continue/Clarify/Abort when stagnation occurs.
• Keep tests and CI fast to make VERIFY iterations effective and avoid false stagnation.

Example use cases

• Implement a new function with tests: iterate RESEARCH → IMPL → VERIFY until tests pass and commit is made.
• Fix a flaky test: detect repeated failing state, prompt for clarification, apply mock or fix, then verify.
• Refactor code across multiple files: repeat IMPL and VERIFY until simplification and tests pass.
• Complete documentation and ticket closure: include docs_updated and ticket_closed as completion indicators.
• Long-running feature that needs multiple validation cycles with commit and marker creation at the end.