Command Reference

Complete reference for all /ll: commands. Run /ll:help in Claude Code for an interactive version.

Flag Conventions

Commands and skills support optional --flag modifiers passed after arguments. These are standard flags used across the project:

Flag	Behavior	Used by
--quick	Reduce analysis depth for faster results	scan-codebase, manage-issue, capture-issue
--parent EPIC-NNN	Bind a captured issue as a child of the named EPIC	capture-issue
--deep	Increase thoroughness, accept longer execution	scan-codebase, audit-architecture, handoff, ready-issue
--focus [area]	Narrow scope to a specific area	scan-codebase
--dry-run	Show what would happen without making changes	manage-issue, align-issues, refine-issue, format-issue, manage-release, audit-issue-conflicts, init, update, publish, decide-issue, wire-issue, improve-claude-md, review-loop, simplify-loop, cleanup-loops, rename-loop
--auto	Non-interactive mode (no prompts). Also activated independently by the LL_NON_INTERACTIVE or DANGEROUSLY_SKIP_PERMISSIONS env var, or by --dangerously-skip-permissions	commit, refine-issue, prioritize-issues, format-issue, confidence-check, spike, verify-issues, map-dependencies, issue-size-review, audit-issue-conflicts, link-epics, audit-loop-run, debug-loop-run, explore-api, decide-issue, wire-issue, go-no-go, scope-epic, review-loop, simplify-loop
--gap-analysis	Additive-only enrichment: fill gaps, never remove content; exempt from max_refine_count via a discriminated Session Log entry (/ll:refine-issue:gap-analysis)	refine-issue
--full-rewrite	Full-rewrite mode (legacy): overwrites sections with research findings	refine-issue
--check	Check-only mode for FSM loop evaluators: run scoring/validation without writes, exit 1 if any fail	ready-issue, verify-issues, confidence-check, issue-size-review, go-no-go, spike, reconcile-issue, map-dependencies, normalize-issues, prioritize-issues, format-issue
--verbose	Include detailed output	align-issues
--all	Process all items instead of a single item	align-issues, format-issue, confidence-check
--sprint <name>	Scope to issues in a named sprint definition	confidence-check, issue-size-review

Not all commands support all flags. See individual command documentation for supported flags.

---

Setup & Configuration

/ll:init

Agentic plan → inspect → apply → verify wrapper over ll-init's --plan/apply seam.

Flags: --force, --dry-run, --hosts, --upgrade, --code-graph, --settings, --no-settings, --no-claude-md

Runs ll-init --plan, then reads the repo to settle any inferred/default-provenance value or listed ambiguity (monorepos, Makefile-driven test targets, custom runners) that the deterministic introspection pass in ll-init couldn't confidently resolve on its own. Applies the corrected plan via ll-init apply --config, then runs the settled test_cmd/lint_cmd once as a smoke check (a failing command is reported as a warning, never a rollback). --dry-run stops after settling and prints the corrected plan instead of applying. A fully-declared repo has nothing to settle, so the flow is nearly as fast as a direct CLI run.

CLI equivalent: ll-init --plan then ll-init apply --config plan.json (the raw two-step dance this skill automates); ll-init --yes remains available for a non-agentic, defaults-only run.

/ll:help

List all available little-loops commands with descriptions.

/ll:configure

Interactively configure specific areas in ll-config.json.

Arguments: - area (optional): project, issues, commands, parallel, automation, documents, continuation, context, prompt, scan, sync, allowed-tools, hooks, design-tokens, learning-tests, analytics, decisions, history, loops.run_defaults

Flags: --list, --show, --reset

Area notes: - allowed-tools — writes to .claude/settings.json or .claude/settings.local.json, not ll-config.json - hooks — shows/validates ll- lifecycle hooks (not ll-config.json; hooks are automatic via plugin)

Version check: configure checks the installed pip package version against the plugin version and prints a non-blocking Warning: pip package version mismatch notification on a mismatch (configure does NOT auto-upgrade; user must run pip install --upgrade little-loops manually).

/ll:update

Update the little-loops Claude Code plugin and pip package to the latest version. Consumer-first: works in any project.

Flags: - --plugin — Update only the Claude Code plugin (claude plugin update ll@little-loops) - --package — Update only the pip package (pip install --upgrade little-loops) - --all — Update both components (same as no flag) - --dry-run — Show what would be updated without making changes

Default behavior: If no component flag is given, both components are updated.

Post-update config health check: After a successful update, the skill validates .ll/ll-config.json against the current config-schema.json and reports any unknown or invalid top-level keys. Prints [PASS] ll-config.json is valid or [WARN] Config issues detected with the offending keys. Non-blocking — a check failure does not fail the overall update. Silently skips when .ll/ll-config.json is not present.

Trigger keywords: "update little-loops", "update plugin", "update package", "ll update"

/ll:publish (maintainers only — project-local, not shipped in plugin)

Bump version in all source files (plugin.json, marketplace.json, pyproject.toml, __init__.py) and commit. Available only in the little-loops source repo via .claude/commands/publish.md — not distributed to consumer projects.

Arguments: - version — New version string (e.g., 1.139.0) or bump level (patch, minor, major) - --dry-run — Preview changes without applying

---

Prompt Optimization

/ll:toggle-autoprompt

Toggle automatic prompt optimization settings.

Settings: enabled, mode, confirm, status (default: status)

---

Code Quality

/ll:check-code

Run code quality checks (lint, format, types).

Modes: lint, format, types, build, all, fix

/ll:run-tests

Run test suites with common patterns.

Arguments: - scope: unit, integration, all, affected - pattern: optional pytest -k filter

/ll:find-dead-code

Analyze codebase for deprecated, unused, or dead code.

/ll:explore-api

Guide the agent through the four-phase Feathers Learning Test lifecycle for an external API, SDK, or library — Ingest → Hypothesize → Execute → Refine — and persist a LearnTestRecord to the Learning Test Registry (.ll/learning-tests/<slug>.md).

Use before writing production code that depends on a third-party system: verifying event shapes, response structures, or return types with a real proof script rather than guessing.

Arguments: - target (required): Free-text description of the system (e.g., "Anthropic SDK streaming") - --assume "<claim>" (repeatable): Pre-seed a claim as assumed-true without running a proof

Flags: --auto (non-interactive) — also activated independently by LL_NON_INTERACTIVE/DANGEROUSLY_SKIP_PERMISSIONS/--dangerously-skip-permissions. When a prior record already exists for the target, an interactive session asks whether to reuse it or run a fresh exploration; under --auto (or the env-var equivalents, which every FSM/loop-driven invocation sets automatically) it always proceeds straight to a fresh exploration that overwrites the record — no prompt.

Outputs: .ll/learning-tests/<slug>.md (YAML frontmatter record) and .ll/learning-tests/raw/<slug>.txt (proof script output)

Registry CLI: ll-learning-tests check "<target>" — returns the saved record (exit 0) or signals a miss (exit 1)

Examples:

/ll:explore-api "Anthropic SDK streaming"
/ll:explore-api "Claude API tool use" --assume "tools is a list" --assume "stop_reason is tool_use"

Trigger keywords: "explore API", "learning test", "prove API behavior", "feathers test"

---

Issue Management

/ll:capture-issue

Capture issues from conversation or natural language description.

Arguments: input (optional) - natural language description

Flags: - --quick - Use minimal issue template (Summary, Behavior, Impact, Status only) - --parent EPIC-NNN - Wire the new issue as a child of the given EPIC: sets parent: in the child's frontmatter and adds the child to the EPIC's ## Children section

Examples:

/ll:capture-issue "retry logic fails on network timeout"
/ll:capture-issue "Add retry logic to sprint runner" --parent EPIC-1663
/ll:capture-issue "Fix log output truncation" --parent EPIC-1626 --quick

/ll:format-issue

Format issue files to align with template v2.0 structure through section renaming, structural gap-filling, and boilerplate inference. Interactive by default, with optional --auto mode for non-interactive formatting.

Arguments: - issue_id (optional): Issue ID to format (e.g., BUG-071, FEAT-225) - flags (optional): - --auto - Non-interactive auto-format mode - --all - Process all active issues - --dry-run - Preview changes without applying - --check - Check-only mode for FSM loop evaluators: dry-run of auto mode, print [ID] format: N gaps found, exit 1 if any gaps, exit 0 if all compliant (implies --auto --dry-run)

/ll:scan-codebase

Scan codebase to identify bugs, enhancements, and features (technical analysis).

Flags: --quick (single-agent scan), --deep (extra verification), --focus [area] (narrow scope)

/ll:scan-product

Scan codebase for product-focused issues based on goals document (requires product.enabled: true).

Prerequisites: - Product analysis enabled in config - Goals file (.ll/ll-goals.md) if present; otherwise goals are discovered automatically from project docs

/ll:prioritize-issues

Analyze issues and assign priority levels (P0-P5).

Flags: - --auto — Non-interactive mode - --check — Check-only mode for FSM loop evaluators: run ll-issues prioritize --check and exit with its exit code

/ll:ready-issue

Validate issue file for accuracy and auto-correct problems.

Arguments: issue_id (optional)

Flags: - --deep — Use sub-agents for comprehensive validation (verifies file paths, line numbers, code snippets against actual codebase) - --check — Check-only mode for FSM loop evaluators: run validation without auto-corrections, print [ID] ready: [verdict], exit 0 if READY/CORRECTED, exit 1 otherwise

Learning Test Gate: When the issue contains a learning_tests_required frontmatter field, each declared target is checked against the learning test registry (ll-learning-tests check). Proven targets emit a PASS row in the VALIDATION table; stale targets emit a WARN. For missing or refuted targets, the skill auto-invokes /ll:explore-api "<target>" inline, then re-checks the registry. If the target is now proven, the gate passes; if it is still missing or refuted after exploration, readiness is blocked with ❌ Unproven assumption: "<target>". Issues without learning_tests_required are unaffected.

Branch-transparent symbol existence (ENH-2653): Before deciding a cited symbol is missing, the verifier reports the inspected branch and worktree (## INSPECTED_BRANCH) so every "symbol not found" claim is falsifiable — a Symbol Existence row of NOT_READY no longer means "missing everywhere," only "missing on the branch named here." When a symbol is absent and the issue is an EPIC child (or the EPIC declares a base_branch:/target_branch:, see FEAT-2652), the verifier downgrades the finding to a WARN ("symbols not on inspected branch <X>; EPIC target base may differ") instead of a hard NOT_READY, since the symbol may simply live on a different base than the one currently checked out. If the EPIC declares no target base, that absence of a declared base is itself flagged as a readiness concern.

/ll:verify-issues

Verify all issue files against current codebase state.

Flags: - --auto — Non-interactive: applies all non-destructive changes without prompting; skips setting resolved issue status - --check — Check-only mode for FSM loop evaluators: run verification without applying changes, print [ID] verify: [verdict] per non-VALID issue, exit 1 if any non-VALID, exit 0 if all valid (implies --auto)

/ll:align-issues

Validate active issues against key documents for relevance and alignment.

Arguments: - category (optional): Document category name (e.g., architecture, product), a .md file path (checks all issues against that document), or --all (all configured categories). When omitted, checks each issue against its own linked documents (linked_docs: frontmatter). - issues (optional): Comma-separated issue IDs to limit processing (e.g., ENH-1362,BUG-123). When omitted, all active issues are processed. - flags (optional): --verbose (detailed analysis), --dry-run (report only, no auto-fixing)

Prerequisites: Configure document tracking via ll-init or /ll:configure documents

/ll:normalize-issues

Find and fix issue filenames lacking valid IDs (BUG-001, etc.).

Arguments: - issue_id (optional): Scope reported/applied findings to this issue - flags (optional): - --auto — Apply all auto-fixable findings without prompting - --check — FSM-gate mode: exit 0 clean / 1 violations, no fixes applied - --strict — Widen --check to also gate on legacy_dir/type_mismatch findings

/ll:sync-issues

Sync local issues with GitHub Issues (push/pull/status).

Arguments: mode (required) - push, pull, or status

/ll:manage-issue

Autonomously manage issues - plan, implement, verify, complete.

Arguments: - type: bug, feature, enhancement - action: fix, implement, improve, verify, plan - issue_id (optional)

Flags: --plan-only, --dry-run (alias for --plan-only), --resume, --gates, --quick (skip deep research), --force-implement (bypass confidence gate)

/ll:iterate-plan

Iterate on existing implementation plans with updates.

Arguments: plan_path (optional)

/ll:refine-issue

Refine issue files with codebase-driven research to fill knowledge gaps needed for implementation. Unlike /ll:format-issue (which aligns structure) or /ll:ready-issue (which validates accuracy), this command researches the codebase to identify and fill knowledge gaps.

Arguments: - issue_id (required): Issue ID to refine (e.g., BUG-071, FEAT-225, ENH-042) - flags (optional): --auto (non-interactive), --dry-run (preview), --gap-analysis (additive-only gap fill, logs /ll:refine-issue:gap-analysis and does not count toward max_refine_count), --full-rewrite (legacy full-rewrite mode)

Frontmatter write-back: After detecting 2+ implementation options deposited into Proposed Solution in --auto mode, the command sets decision_needed: true in the issue's YAML frontmatter. If fewer than 2 options are deposited, the flag is cleared to false (or left absent if never set). This is skipped in --dry-run mode. Note: /ll:confidence-check can also set decision_needed: true independently when it detects an unresolved decision in Outcome Risk Factors.

/ll:decide-issue

Resolve multi-option implementation decisions by gathering codebase evidence for each option and selecting the best fit. Where /ll:refine-issue --auto deposits competing approaches and sets decision_needed: true (or /ll:confidence-check detects an unresolved decision), this skill closes the loop — scoring every option and annotating the winner directly in the issue file.

Arguments: - issue_id (required): Issue ID to decide on (e.g., FEAT-948, ENH-277) - flags (optional): --auto (non-interactive), --dry-run (preview decision without writing), --validate-only (probe decidability only — Phases 1–2.5, no scoring, no writes; exit 0 if there is something to decide, exit 1 with OPTIONS_MISSING otherwise)

When to run: After /ll:refine-issue --auto or /ll:confidence-check sets decision_needed: true in the issue frontmatter. Automated pipelines (ll-auto, ll-parallel) invoke this step automatically via the decide_command config template.

Decidability gate (ENH-2443): Phase 2.5 calls ll-issues locate-options --json to count enumerable options in ## Proposed Solution before scoring — Phase 3 makes the same call for option spans/scoring, plus (BUG-3278) ll-issues check-unresolved-decisions to source its candidate decision group, so the pattern precedence (section headers, bold labels, numbered/bullet items, the bold-numbered decision_rules_numbered structural heuristic under ## Program Design → ### Decision Rules, then the un-preferenced-directive heuristic) is defined once, in issue_parser.py, and never re-derived in skill prose (ENH-2950). The un-preferenced-directive heuristic (Pattern E) is not purely a last resort: locate_enumerable_options() also probes it alongside an earlier tier/H2 match (BUG-3287), so a document that already has formal options can still surface a separate, un-preferenced directive elsewhere as a non-null residual_directive on the winning result (locate-options --json → {"count": 2, "pattern": "bold_label", ..., "residual_directive": {"pattern": "provisional_e", ...}}) — Phase 3's count == 1 branch additionally checks residual_directive is None before clearing decision_needed, so a residual directive is never silently cleared away. If decision_needed: true but zero enumerable options are found, --auto mode invokes /ll:refine-issue --auto once (bounded, internal --deposit-attempted flag) to deposit options, then re-checks. If still zero, control falls through to Phase 3 → Phase 3b's inline provisional-language scan (BUG-2606) rather than giving up immediately — Phase 3b can still lock in a clear winner from prose recommendations even when no formal ### Option A/B blocks exist. Phase 3b's Pattern E (ENH-2936) additionally routes an un-preferenced decision directive — 2+ named alternatives co-occurring with an imperative decide-marker ("do not leave unaddressed", "decide before implementation") but no stated preference — through full Phase 4–7 evidence-based scoring instead of requiring a textually-identifiable winner up front; locate-options --json reports this as pattern: "provisional_e" with the matched window as its single option span. Only if Phase 3b also finds no clear winner and no Pattern E match does decision_needed stay true. FSM callers (rn-remediate, autodev) use the deterministic companion CLI ll-issues check-decidable <ID> (no LLM) as a cheap pre-decide gate — mirrors ensure_formatted → ll-issues format-check (ENH-2426); ll-issues locate-options <ID> --json is the data-frontend sibling when a caller needs the actual option spans, not just a boolean.

Frontmatter write-back (conditional, BUG-3278): after annotating the winning option, both write sites — Phase 7b and Phase 3b step 4 — re-verify via ll-issues check-unresolved-decisions before clearing, because an issue can hold more than one decision point (a **Option A/B/C** block plus a separately-formatted - (a)/(b) bullet pair in the same section, for example) and Phase 3's extraction resolves only the highest-precedence one. decision_needed: false is written only on exit 0 (no unresolved decision group remains — the unit of resolution is the group, not the option block, so a correctly-decided group's losing options do not block the clear); on exit 1/2+ the flag stays true and the surviving group(s) are named in the Phase 9 report. In --auto mode when no formal Option A / Option B blocks are found (Phase 3b), also scans all sections for inline provisional decision language ((e.g., ...), TBD, "must be replaced with") and, if a single clear approach is identifiable, locks it in — adding a > **Selected:** callout on the winning block when structured options exist, so the residual-decision gate can see it resolved — before the same conditional clear. If no clear winner can be inferred, exits cleanly without prompting, leaving decision_needed unchanged. Idempotent per-group — skips the annotation write only when the selected group itself already carries a resolution marker, not merely when any ### Decision Rationale section exists in the issue.

Selection propagation (Phase 7c, ENH-3280): after Phase 7b takes its exit-0 branch (and never under --dry-run), Phase 7c reads ll-issues format-check <ID> --format json's unapplied_decision_detail key — structured {section, identifier} pairs for rejected-option identifiers still present in a directive section — and rewrites the ones whose surrounding prose matches one of four categories (a recommendation marker naming the loser, an option-keyed conditional block, an imperative implementation step, or an explicit propagation checklist the issue itself names); every other candidate is flagged in the Phase 9 report and left untouched (bounded scope — a decision pass must not become a refine pass). Idempotent on content-presence: if unapplied_decision is already empty, Phase 7c skips and logs rather than re-scanning.

Decisions log (decide-issue): When decisions log is enabled, appends a decision entry to the log (as an append-only .ll/decisions.d/*.json fragment). Silently skipped if the log is absent (neither .ll/decisions.yaml nor .ll/decisions.d/).

/ll:wire-issue

Post-refinement wiring pass that completes an issue's Integration Map — the structured record of every file that must change when the issue is implemented. Where /ll:refine-issue fills in the what and why, wire-issue traces the where: every caller, importer, config entry, doc section, test file, replaced-artifact behavior, and side-effect file that the implementation will touch. It may additionally annotate a directive line that its own wiring additions contradict with an inline ⚠ Superseded marker (ENH-2995, ENH-3049) — never a rewrite, and wire may only insert markers, never delete one.

The Integration Map lives in the issue file under ## Integration Map. A thin map might list 3–5 files; a wired map covers 10–20+, including non-obvious side effects like __init__.py exports, CLI registration hooks, and plugin manifests. Thin maps are the primary cause of incomplete implementations.

When to run: After /ll:refine-issue when the Integration Map section looks sparse — few files listed, no test files, no doc sections. Also before /ll:confidence-check to ensure the readiness score reflects full scope.

Wiring categories searched: - Callers: functions/classes in other modules that call the target code - Config: keys in ll-config.json, config-schema.json, plugin.json - Tests: existing test files that cover the area, test files that should be created/updated - Docs: sections in docs/ that describe the changed behavior - Side effects: __init__.py exports, CLI entry points, hook registrations, marketplace entries - Behavior Parity (ENH-3045): when the issue rewrites, deletes, or delegates away an existing file, each of that file's behaviors is enumerated with a preserved/changed/dropped disposition - gate_consumers (ENH-3050): when the change adds/alters a field in a CLI's --format json output or an exit-code condition, every loop/hook/skill/command/doc file that reads that CLI's output — traced by grepping the invocation string, not the Python symbol - conditional_branches (ENH-3050): when the plan states a conditional fallback naming an alternate implementation target ("if X overflows, do Y"), that target's own touchpoints are wired as first-class

Arguments: - issue_id (optional): Issue ID to wire (e.g., FEAT-948, ENH-277). Reads most recent active issue if omitted.

Flags: --auto (non-interactive), --dry-run (preview without writing)

Trigger keywords: "wire issue", "missing integration points", "complete the wiring", "trace dependencies", "wiring pass"

/ll:reconcile-issue

Rewrite an issue's ## Implementation Steps, ## Acceptance Criteria, and ### Files to Modify in place from its own accumulated research findings, without appending or bulldozing human prose. Over a long refine/spike/confidence-check cycle, /ll:refine-issue and /ll:confidence-check only append new "Codebase Research Findings" bullets — they never rewrite the issue's own directive sections to match, so a stale section keeps re-flagging the same Concern and the Readiness score plateaus. (/ll:refine-issue can additionally annotate a refuted directive line in place with an inline ⚠ Superseded marker, ENH-2995 — the original line stays untouched and the marker is not a rewrite; it just makes the contradiction visible until a reconcile-issue pass replaces the section wholesale.) reconcile-issue closes that loop with a targeted, in-place rewrite of those three unconditional sections, plus one conditional case (ENH-2937): a ## Scope Boundaries claim whose stated justification is directly contradicted by a recorded finding in the same issue may be rewritten (factual correction) or turned into an explicit decision directive (decision_needed: true) — unrefuted Scope Boundaries prose, and every other section (Summary, Motivation, Proposed Solution, Codebase Research Findings, Wiring Phase, Confidence Check Notes, Session Log, etc.), is left untouched.

Arguments: - issue_id (required): Issue ID to reconcile (e.g., FEAT-2672, BUG-004) - flags (optional): --check (report the plateau verdict without writing — exit 0 if a reconcilable plateau exists, exit 1 if the body is already clean; for FSM evaluate: type: exit_code routing)

One-shot guard: Sets reconcile_attempted: true in the issue's frontmatter immediately on invocation (even on a no-op rewrite), mirroring /ll:spike's spike_attempted convention. This arms autodev.yaml's check_reconcile_needed one-shot guard so the readiness-driven branches (plateau, fresh-below-threshold) run at most once per issue per autodev run. The ENH-2992 contradiction branch is deliberately not gated by this flag — it is permanent frontmatter no state clears, so gating on it would make a second reconcile structurally impossible; that branch is bounded by marker clearing plus a reconcile-scoped per-issue cap of 2 instead.

Marker clearing (ENH-2992): Deletes the > ⚠ Superseded — … annotation on every directive line it evaluated — not only the lines it rewrote, and including on the no-op branch, where clearing is then the pass's only edit. A marker means "this pass's findings refute this line"; once reconcile has adjudicated the line, the annotation is consumed. Deletion is silent (no tombstone, no CORRECTIONS_MADE entry) and only marker lines are ever removed, matching /ll:refine-issue's existing "bounded marker-removal right". --check mode never writes, so it never clears.

When to run: After a spike proves a mechanism but Readiness stays bit-identical to its pre-spike score (the plateau autodev.yaml's check_reconcile_needed state detects, ENH-2689) — or whenever a refine pass has left a ⚠ Superseded marker in a directive section (ll-issues format-check [ID] --format json → superseded_marker_count > 0), which is the ENH-2992 contradiction branch and what /ll:refine-issue's own Next Steps block now points at. Also user-invocable directly to unstick an issue whose directive sections have drifted from its accumulated research.

Distinct from: /ll:refine-issue (appends new research, and may annotate a refuted directive line in place — never a rewrite), /ll:ready-issue (reconciles issue ↔ codebase accuracy), and /ll:wire-issue (adds integration touchpoints) — this command reconciles the issue against itself.

Trigger keywords: "reconcile issue", "rewrite stale sections", "readiness plateau", "directive sections out of date"

/ll:tradeoff-review-issues

Evaluate active issues for utility vs complexity trade-offs and recommend which to implement, update, or close.

Arguments: - issues (optional): Comma-separated issue IDs to filter (e.g., BUG-123,FEAT-456). If omitted, scans all active issues.

Decisions log: When decisions log is enabled, appends a decision entry to the log (as an append-only .ll/decisions.d/*.json fragment). Silently skipped if the log is absent (neither .ll/decisions.yaml nor .ll/decisions.d/).

Trigger keywords: "tradeoff review", "review issues", "prune backlog", "sense check issues"

/ll:audit-issue-conflicts

Scan all open issues for conflicting requirements, objectives, or architectural decisions — outputs a ranked conflict report (high/medium/low severity) with recommended resolutions. Conflict types: requirement contradictions, conflicting objectives, architectural disagreements, scope overlaps.

Arguments: - epic-id (optional): Positional EPIC-NNNN (bare NNNN accepted). When set, scopes the audit to that EPIC's transitive children (cycle-guarded, via ll-issues list --parent) plus the EPIC file itself, instead of the full active backlog. A non-EPIC positional aborts with a clear message. - Positional alternative — comma-separated issue-ID list (e.g. BUG-123,ENH-456,FEAT-555, bare NNN per token accepted): scopes the audit to exactly those issues, with no transitive expansion. Each ID is resolved independently via ll-issues path; an unresolvable ID aborts with a message naming the offending token.

Flags: --auto (apply all recommendations without prompting), --dry-run (report only, no changes written), --cross-theme (add Phase 2b cross-batch fingerprint sweep to catch conflicts between issues in different thematic groups — uses ll-issues fingerprint to find file-overlap pairs across batch boundaries without an LLM call, then dispatches targeted single-pair agents only for overlapping pairs)

Trigger keywords: "audit conflicts", "conflicting issues", "requirement conflicts", "check for contradictions"

/ll:product-analyzer

Analyze codebase against product goals to identify feature gaps, user experience improvements, and business value opportunities. Returns raw YAML findings; use /ll:scan-product for full workflow with issue file creation.

Arguments: - focus-area (optional): Limit analysis to a specific goal ID, persona, or one of gaps|ux|opportunities

Prerequisites: - Product analysis enabled in config (product.enabled: true) - Goals file (.ll/ll-goals.md) if present; otherwise goals are discovered automatically from project docs

/ll:confidence-check

Pre-implementation confidence check that validates readiness and estimates outcome confidence before coding begins. Produces dual scores: a Readiness Score (go/no-go) and an Outcome Confidence Score (implementation risk).

Arguments: - issue_id (optional): Specific issue to check

Flags: --auto (non-interactive), --all (batch all active issues), --sprint <name> (scope to sprint issues only), --check (check-only mode: run scoring without writes). Only failing issues print a score line — [ID] check: score N/100 (below threshold); issues at or above the threshold print nothing. After all issues, prints either N issues not ready and exits 1, or All issues pass confidence check and exits 0

Findings write-back: When concerns, gaps, or outcome risk factors are found (and --check is not set), the skill automatically appends a ## Confidence Check Notes section to the issue file and stages it with git add — no confirmation prompt. This fires in both interactive and --auto modes. If all scores are clean, no write occurs.

Hard overrides: independently of the aggregate score, the verdict forces STOP — ADDRESS GAPS when any of: a declared learning_tests_required target is missing/refuted; the Program Design gate fails (.ll/program-design-cutover.json armed, issue not grandfathered); or an issue's blocked_by frontmatter names an ID whose status is not done/cancelled (deferred is non-terminal) — the last is the Dependencies Hard Override (BUG-3051), listing the unresolved ID(s) and their status under Gaps to Address.

Claim/parity gap cap (ENH-3047): before scoring, the skill pre-fetches ll-issues format-check's missing_behavior_parity, stale_symbol_ref, and stale_cli_flag gap keys for the target issue. A non-empty hit on any of these caps Criterion 4 (Issue Well-Specified) at 10 regardless of which row would otherwise apply — a ceiling, never a floor. Unlike the hard overrides above, this does not force a STOP verdict; it only bounds one criterion's score, since forward-looking design/planning claims legitimately do not resolve yet.

Flag write-back (ENH-2946): After writing Outcome Risk Factors, the skill delegates to ll-issues set-flags [ISSUE-ID], which reads the issue's own ## Confidence Check Notes section and applies the phrase-list + numeric-gate rules in FLAG_RULES (scripts/little_loops/cli/issues/set_flags.py) — the CLI is the single source of truth for these rules, not skill prose. Skipped in --check mode. Set-only: a flag already true is never cleared by a re-run whose notes no longer match.

• decision_needed: signal phrases ("open decision", "unresolved decision", "resolve before implementing", "decision point", "either/or", "either...or", "resolve before starting", "open question", "Option A/B", "Option A or"). This ensures the autodev loop's decision gate fires automatically for issues where confidence-check identified an unresolved blocking decision.
• missing_artifacts: signal phrases indicating absent files or unwired components ("not yet created", "does not exist", "needs wiring", "missing artifact", "absent", "unwired component"). Suppressed when the absent file is listed under the issue's own ### Files to Create section (a co-deliverable, not a genuine pre-condition gap) — implementation_order_risk fires instead when that suppression applies.
• implementation_order_risk: signal phrases indicating implementation ordering advice rather than a true wiring gap ("co-deliverable", "implement tests first", "write tests before", "test-first", "tests are co-deliverables", "implement first so"), or fired because missing_artifacts' co-deliverable suppression applied this run. Captures ordering concerns that should NOT trigger the run_wire repair path in autodev — they belong in the Implementation Steps body text.

/ll:spike

Retire concentrated technical risk on an issue by planning, implementing, and verifying a code spike — a standalone library plus test class that proves a novel internal mechanism in isolation — before the real integration point is touched.

Arguments: - issue_id (required): Issue whose risk the spike must retire

Flags: --auto (non-interactive), --check (check-only FSM evaluator mode, implies --auto), --plan-only (stop after writing the plan doc), --plan <file> (implement a caller-supplied plan, skipping risk extraction), --force (override the one-spike-per-issue budget)

When to use: after /ll:confidence-check sets spike_needed: true (its Phase 4.10 failure mode) because a mechanism has zero precedent in the codebase and no test exercises the risky core. Not for unproven external API assumptions (use /ll:explore-api + the Learning Test Registry), unresolved Option A/B ambiguity (/ll:decide-issue), absent files or unwired integration (/ll:wire-issue), or an over-large issue (/ll:issue-size-review). If the extracted risk factor names a third-party package or external API surface, the skill refuses and redirects to /ll:explore-api.

Flow: locate issue (ll-issues path) → extract risks from ## Confidence Check Notes → ### Outcome Risk Factors → write a plan doc to ${context.run_dir} (inside an FSM loop) or .ll/spikes/ (interactive) in the shape of skills/spike/plan-template.md → implement under scripts/tests/spike/<slug>/ → verify with the plan's pytest commands → write back → recommend the next step. Spike code lives only under scripts/tests/spike/; production files under scripts/little_loops/ are read-only in this skill (enforced by allowed-tools).

Budget discipline: one spike per issue. If the frontmatter already carries spike_attempted: true, the skill refuses and exits 0 unless --force is passed.

Write-back: on success, appends ## Spike Results (retired-risk table, spike location, verification counts, promotion note) and sets both spike_completed: true and spike_attempted: true. On failure, sets only spike_attempted: true and appends ## Spike Findings documenting what was disproven and which approach it rules out. Either way it appends a session log via ll-issues append-log and git adds the issue file. Skipped entirely in --check mode.

--check mode: runs the spike's AC suite with no writes and exits 0 (pass) / 1 (fail), matching FSM evaluate: type: exit_code routing. The spike-gate.yaml wrapper loop (ENH-2641) consumes this contract to gate an implementation loop on a proven internal mechanism.

Related frontmatter: spike_needed, spike_attempted, spike_completed — see ISSUE_TEMPLATE.md.

/ll:issue-workflow

Quick reference for the little-loops issue management workflow. Displays the issue lifecycle diagram and command order.

Trigger keywords: "issue workflow", "issue lifecycle", "what commands for issues"

/ll:issue-size-review

Evaluate the size and complexity of active issues and propose decomposition for large ones. Assigns a complexity score (1–10) based on file count, section count, scope of changes, and estimated session time. Issues scoring 8 or above are flagged as candidates for decomposition.

When to use: After refinement, before sprint planning. Signals that an issue may be too large: the Integration Map touches >8 files, the Proposed Solution has >5 distinct steps, or the issue spans multiple unrelated subsystems.

Scoring scale: 1–4 = small (implement directly); 5–7 = medium (review scope before implementing); 8–10 = large (decompose before implementing).

Decomposition output: For each oversized issue, proposes 2–4 smaller child issues with independent scopes, clear dependencies between them, and a suggested execution order. Child issues can be created directly from the output.

Frontmatter write-back: After assessing each issue, the skill writes size: <label> to the issue's YAML frontmatter (one of: Small, Medium, Large, Very Large). This is skipped when --check mode is active.

TDD awareness: The skill respects config.commands.tdd_mode. When true, decomposition proposals must not split wiring from the implementation that introduces it — wiring is part of the TDD cycle and belongs in the same child (see skills/issue-size-review/SKILL.md Phase 4 for the full rule and the "independently shippable" exception).

Flags: - --auto: Non-interactive; auto-decomposes issues scoring ≥8 without prompting. Exception: if the issue has score_ambiguity ≥ 18, score_complexity ≥ 18, and a non-zero outcome_confidence in its frontmatter, decomposition is skipped — the confidence failure is qualitative, not a scope problem (see qualitative-skip guard) - --check: Check-only mode; runs scoring without decomposition or frontmatter write-back; exits 1 if any issues score ≥5 - --sprint <name>: Scope to issues in a named sprint definition only

Trigger keywords: "issue size review", "decompose issues", "split large issues"

/ll:go-no-go

Evaluate whether one or more issues should be implemented using an adversarial debate format. Launches two isolated background agents concurrently — one arguing for implementation, one against — each grounded in real codebase research. A third judge agent delivers a final GO or NO-GO verdict with structured reasoning, key arguments from both sides, and a deciding factor.

Arguments: - issue-id (optional): One or more comma-separated issue IDs, or a sprint name. Defaults to the highest-priority open issue.

Flags: - --check: Exit 0 on all GO, exit 1 on any NO-GO — enables FSM loop gating via evaluate: type: exit_code - --auto: Non-interactive mode (skips write-back prompt; writes findings directly)

NO-GO REASON sub-classification: When the verdict is NO-GO, a structured reason is included indicating the recommended next action:

Reason	Meaning	Recommended action
CLOSE	Issue is invalid, already covered, or misdirected	Close (set status: done in frontmatter)
REFINE	Issue is valid but under-specified or needs more research	Run /ll:refine-issue or /ll:ready-issue
SKIP	Good idea but poorly timed or lower priority than active work	Keep open, deprioritize, or remove from sprint

The reason appears inline in verdict output (NO-GO ✗ (CLOSE)), batch summaries, and --check mode per-issue lines.

Findings write-back: After rendering a verdict, go-no-go checks whether the judge's output references specific files or functions not already in the issue body. If significant new information is found, it offers to insert a ## Go/No-Go Findings section into the issue file (before ## Session Log, anchored on the blank line above the heading so the existing ## Session Log heading is kept verbatim — BUG-3424). In --auto mode the write happens without prompting; in --check mode writes are skipped entirely.

Decisions log: When decisions log is enabled, appends a decision entry to the log (as an append-only .ll/decisions.d/*.json fragment). Silently skipped if the log is absent (neither .ll/decisions.yaml nor .ll/decisions.d/).

Trigger keywords: "go no go", "should I implement", "adversarial review", "worth implementing", "debate this issue"

/ll:advise

One-shot, signal-cited consult to a different (typically stronger) model for a second opinion on a stalled or ambiguous decision. Requires an explicit signal naming why the consult is happening — never auto-triggered without cause.

Flags: - --signal SIGNAL (required): Why this consult is happening (e.g. user_requested, score_stall) - --question QUESTION (required): The question to ask the advisor model - --context-file PATH (optional): Path to a file with supporting context. Never auto-slurps the working tree — only what's explicitly included. - --host HOST (optional): Host CLI to run the advisor through (default: configured host) - --model MODEL (optional): Advisor model override

Example: /ll:advise --signal score_stall --question "Is this decomposition correct?" --context-file notes.md

/ll:map-dependencies

Analyze active issues to discover cross-issue dependencies based on file overlap, validate existing dependency references, and propose new relationships. Delegates to ll-deps CLI subcommands.

Flags: - --auto — Non-interactive mode: apply all HIGH-confidence dependency proposals without prompting, skip MEDIUM-confidence proposals - --check — Check-only mode for FSM loop evaluators: run dependency analysis without applying changes, print [ID] deps: N unmapped dependencies per issue with unmapped deps, exit 1 if any unmapped, exit 0 if all mapped (implies --auto)

Trigger keywords: "map dependencies", "dependency mapping", "find dependencies"

/ll:link-epics

Discover parentless open issues and either assign them to existing open EPICs (--mode assign, default) or cluster them by similarity into proposed new EPICs (--mode synthesize). Scoring, tiering, and clustering are delegated to the ll-issues link-epics CLI (title word-overlap similarity); this skill presents the CLI's proposals and, in synthesize mode, names/creates the resulting EPIC files (EPIC creation is not yet part of the CLI itself).

Flags: - --mode assign|synthesize — assign (default) links orphans to existing EPICs; synthesize clusters orphans and proposes new EPIC files - --threshold <score> — minimum similarity score (float, e.g. 0.5) to include; default config.issues.link_epics.min_score - --auto — apply/create all proposals without prompting - --deep — --mode synthesize only; adds one batched LLM-adjudicated clustering pass (capped at 40 orphans) merged with the Jaccard clusters, for thematically related issues that don't share vocabulary (ENH-2979). --deep-sourced clusters carry cited evidence and a source field, reviewed in S2

Output: In assign mode, writes parent: <EPIC-NNN> and epic: <EPIC-NNN> to each accepted child issue's frontmatter and appends it to the EPIC's ## Children section (via ll-issues link-epics --apply). In synthesize mode, creates new EPIC files for accepted clusters and writes parent:/epic: back to each child.

Trigger keywords: "link epics", "assign to epic", "parentless issues", "orphan issues", "cluster orphaned issues", "synthesize epics"

---

Sprint Management

/ll:create-sprint

Create a sprint definition with a curated list of issues.

Arguments: - name (required): Sprint name (e.g., "sprint-1", "q1-bug-fixes") - description (optional): Description of the sprint's purpose - issues (optional): Comma-separated list of issue IDs (e.g., "BUG-001,FEAT-010")

Modes: - Explicit: Pass --issues "BUG-001,FEAT-010" to create a sprint with specific issues - Auto-Grouping: When issues is omitted, suggests natural sprint groupings: - Priority cluster (P0-P1 critical), type cluster (bugs/features/enhancements) - Parallelizable (no blockers), theme cluster (test, performance, security) - Manual Selection: Choose "Select manually" to pick issues interactively

Output: Creates .sprints/<name>.yaml with issue list and execution options.

/ll:review-sprint

AI-guided sprint health check that analyzes a sprint's current state and suggests improvements.

Arguments: - sprint_name (optional): Sprint name to review (e.g., "my-sprint"). If omitted, lists available sprints.

Trigger keywords: "review sprint", "sprint health", "sprint review", "check sprint", "sprint suggestions", "optimize sprint"

Output: Recommendations for removing stale issues, adding related backlog issues, and resolving dependency or contention problems. When any sprint member has a parent: referencing an EPIC, the output also includes an EPIC Context section that flags critical-path blocker gaps — EPIC children not in the sprint whose absence would stall a sprint member — with a concrete ll-sprint edit --add fix command for each gap.

---

/ll:review-epic

Read-only health audit for an EPIC: surfaces stalled children, flags scope drift, identifies missing coverage, and recommends closure when all children are done.

Arguments: - epic_id (required): EPIC ID to review (e.g., "EPIC-42") - --skip-drift (optional): Skip LLM scope-drift and missing-coverage passes; emit structural findings only (stall detection + closure check)

Trigger keywords: "review epic", "epic health", "epic audit", "epic progress", "check epic", "stalled children", "scope drift", "epic ready to close"

Output: A structured health report with progress summary, stalled children, scope-drift findings, missing-coverage findings, closure recommendation, and related (not children) — followed by a numbered Recommendations section mapping each finding to a concrete runnable command. Never writes to any file.

---

/ll:scope-epic

Decompose a high-level theme or goal into an EPIC issue file and 3–8 pre-wired child issue stubs with parent: EPIC-NNN frontmatter. Presents an interactive review table before writing; cancellation writes nothing.

Arguments: - theme (required): Natural-language theme or goal description to decompose - --from-doc <path> (optional): Read the theme from a markdown file instead of the argument string - --priority <P0-P5> (optional): Override the default EPIC priority (default: P2) - --auto (optional): Non-interactive mode — skips the interactive review table and writes EPIC + child stubs directly. Designed for FSM loop callers (e.g., rn-build scope_project state) where no human is present to confirm the decomposition.

Trigger keywords: "decompose theme", "scope epic", "create epic from", "break down initiative", "epic decomposition", "theme to epic", "create child issues"

Output: Writes the EPIC file (full template) to .issues/epics/, writes each child stub (minimal template) to the appropriate type directory, wires ## Children on the EPIC, sets parent: on each child, and stages all files for git. Prints a summary table and next-step hints.

---

Auditing & Analysis

/ll:audit-architecture

Analyze codebase architecture for patterns and improvements.

Focus: large-files, integration, patterns, organization, all

Flags: --deep (spawn sub-agents for thorough analysis)

/ll:audit-docs

Audit documentation for accuracy and completeness. Auto-fixable findings (wrong counts, outdated paths, broken links) can be fixed directly during the audit.

Scope: full, readme, file:<path>, dir:<path> (or a bare directory path, e.g. docs/guides/) — all markdown under a directory

Flags: --fix (auto-apply fixable corrections without prompting)

/ll:update-docs

Identify stale or missing documentation by analyzing git commits and completed issues since a given reference. Detects coverage gaps from recent work — complements /ll:audit-docs (which validates accuracy of existing content).

Flags: - --since (optional): Change window start — date (YYYY-MM-DD) or git ref (commit hash or branch). Defaults to last commit touching a doc file, or the watermark in .ll/ll-update-docs.watermark if present. - --fix (draft stub documentation sections inline for all gaps rather than prompting)

Trigger keywords: "update docs", "stale docs", "missing docs", "docs since sprint", "doc coverage", "documentation gaps"

/ll:audit-claude-config

Comprehensive audit of Claude Code plugin configuration with parallel sub-agents.

Scope: all, managed, user, project, hooks, mcp, agents, commands, skills, output-styles, lsp, keybindings, claudeignore, plugin-settings, settings

Flags: --non-interactive, --fix

/ll:improve-claude-md

Rewrite a project's CLAUDE.md using <important if="condition"> XML blocks. Applies the 9-step rewrite algorithm: leave foundational context (project identity, directory map, tech stack) bare; wrap commands in one block; break apart rules into individual narrow-condition blocks; wrap domain sections; delete linter-territory, code snippets, and vague instructions.

Flags: - --dry-run — Preview the rewrite plan without modifying any file - --file <path> — Target a specific file (default: .claude/CLAUDE.md or ./CLAUDE.md)

Trigger keywords: "improve claude md", "rewrite claude md", "important if blocks", "instruction adherence", "restructure claude md"

/ll:analyze-workflows

Analyze user message history to identify patterns, workflows, and automation opportunities.

Arguments: - file (optional): Path to user-messages JSONL file (auto-detected if omitted)

/ll:analyze-history

Analyze issue history to understand project health, trends, and progress. Delegates to ll-history CLI subcommands (summary, analyze, export). The export subcommand compiles topic-filtered issue excerpts from completed issue history.

Trigger keywords: "analyze history", "velocity report", "bug trends", "project health"

---

Git & Workflow

/ll:commit

Create git commits with user approval (no assistant attribution — Claude, Qwen, or any other agent). Supports --auto flag for non-interactive use in automation contexts.

/ll:describe-pr

Generate comprehensive PR descriptions from branch changes.

Arguments: - base_branch (optional, default: auto-detect): Base branch for PR comparison. If omitted, auto-detects from refs/remotes/origin/HEAD (usually main or master).

/ll:open-pr

Open a pull request for the current branch.

Arguments: - issue_id (optional): Issue ID (e.g. ENH-2175) to read branch:/pr_url: from issue frontmatter. If omitted, auto-detected from the current branch name. - target_branch (optional): Target branch for the PR (default: auto-detect)

Flags: --draft (create as draft PR)

/ll:cleanup-worktrees

Clean orphaned git worktrees and branches from interrupted ll-parallel or ll-loop runs. Delegates to ll-parallel --cleanup-orphans, which uses the canonical Python orphan-detection logic: selects only ll-managed worktrees (worker-* or YYYYMMDD-HHMMSS-*), skips worktrees owned by live processes — an out-of-tree liveness registry entry (ENH-3376) is the primary signal, since it survives a git clean -fdx run inside the worktree that would erase the in-tree session marker; the marker is only consulted when no registry entry exists. When neither the registry nor the marker finds a live signal, a last-resort fallback (ENH-3377) checks whether any live process's cwd is inside the worktree, skipping with a warning (naming the blocking pid/process) instead of deleting if so, or if the check itself cannot be performed — and deletes both the directory and its branch (parallel/* and loop-style).

Arguments: - mode: run (default), dry-run

/ll:manage-release

Manage releases — create git tags, generate changelogs, and create GitHub releases.

Arguments: - action (optional): tag, changelog, release, bump, full (interactive if omitted) - version (optional): vX.Y.Z, patch, minor, major (auto-detects if omitted)

Flags: --dry-run, --push, --draft

---

Session Management

/ll:handoff

Generate continuation prompt for session handoff.

Arguments: - context (optional): Description of current work context

Flags: - --deep — Validate and enrich with artifacts (git status, todos, recent files) instead of relying only on conversation history

/ll:resume

Resume from a previous session's continuation prompt.

Arguments: - prompt_file (optional): Path to continuation prompt (default: .ll/ll-continue-prompt.md)

---

Automation Loops

/ll:create-loop

Create FSM loop configurations — interactively or from a natural language description.

Arguments (optional): - description — Natural language description of the loop. When provided, the skill infers loop type and parameters, shows a confirmation summary, and jumps directly to YAML preview — skipping the guided wizard.

Workflow (no args — interactive): 1. Select loop type (fix-until-clean, maintain-constraints, drive-metric, run-sequence, harness, RL variants, policy-router, meta-optimize, orch-router) 2. Configure type-specific parameters 3. Name and preview the FSM YAML 4. Save to .loops/<name>.yaml and validate

Workflow (with args — fast path): 1. Infer loop type and parameters from description 2. Confirm inferred values (or fall back to guided wizard with pre-filled defaults) 3. Preview, save, and validate

Usage:

/ll:create-loop
/ll:create-loop run mypy and ruff until they both pass
/ll:create-loop reduce lint errors to zero using ruff check, max 8 iterations
/ll:create-loop harness the refine-issue skill and iterate until the issue is implementation-ready
/ll:create-loop maintain tests passing and types clean, call it quality-guardian
/ll:create-loop route a goal to the right loop for this project

See also: docs/generalized-fsm-loop.md for FSM schema details.

/ll:create-eval-from-issues

Generate a ready-to-run FSM eval harness YAML from one or more issue IDs. Reads each issue's Expected Behavior, Use Case, and Acceptance Criteria sections to synthesize a natural-language execute prompt and llm_structured evaluation criteria — no hand-authoring required.

Also supports --dsl <source-file> to generate DSL-native fill-in-the-blank/transform/correction tasks from a loop YAML or issue file.

Arguments: - issue_ids (required without --dsl): One or more issue IDs (e.g., FEAT-919, ENH-950). Accepts open and completed issues. - --dsl <source-file> (optional): Path to a loop YAML or issue file. Generates DSL-native eval tasks under evals/dsl/<source-name>/ instead of an FSM harness. Run the generated tasks with ll-harness dsl evals/dsl/<source-name>/.

Output (standard mode): .loops/eval-harness-<slug>.yaml, generated via ll-loop scaffold-eval (little_loops.cli.loop.scaffold_eval) and validated in-process with fsm.validation.validate_fsm() before the skill fills its <EXECUTE_PROMPT>/<EVALUATION_CRITERIA_PROMPT> placeholders and writes the file

Output (DSL mode): evals/dsl/<source-name>/task-01.yaml, task-02.yaml, ... (Option B lightweight schema)

Variants (standard mode): - Single issue → Variant A: initial: execute, states: execute → check_skill → done - 2+ issues → Variant B: initial: discover, states: discover → execute → check_skill → advance → done

No check_invariants: eval harnesses measure user experience quality, not code diff size.

Usage:

/ll:create-eval-from-issues FEAT-919
/ll:create-eval-from-issues FEAT-919 ENH-950
/ll:create-eval-from-issues --dsl loops/my-loop.yaml
/ll:create-eval-from-issues --dsl .issues/enhancements/P3-ENH-2081-example.md

See also: docs/guides/AUTOMATIC_HARNESSING_GUIDE.md, /ll:create-loop

/ll:verify-issue-loop

Generate a ready-to-run FSM verification loop YAML from a single issue ID. Two modes: criteria (default) walks each acceptance criterion in order and asks an LLM whether the implementation satisfies it, failing fast on any criterion that fails; adversarial tries to break the feature via three distinct probe classes — boundary values, malformed/hostile inputs, and failure modes — rather than confirming it works. Verification counterpart to /ll:create-eval-from-issues: where create-eval-from-issues exercises a feature as a user would, verify-issue-loop checks that the implementation meets each acceptance criterion (or survives adversarial probing).

Arguments: - issue_id (required): A single issue ID (e.g., FEAT-919, ENH-950, BUG-347). Accepts open or completed issues. - mode (optional): criteria (default) or adversarial. Absent mode resolves silently to criteria.

Output: .loops/verify-<ISSUE-ID>-<slug>.yaml (criteria mode) or .loops/adversarial-<ISSUE-ID>-<slug>.yaml (adversarial mode), generated via ll-loop scaffold-verify (little_loops.cli.loop.scaffold_verify) and validated in-process with fsm.validation.validate_fsm() before the skill writes the file. Unlike create-eval-from-issues, the emitted YAML is immediately runnable — no placeholder slots remain.

Structure: - mode: criteria — one verify-criterion-N state per acceptance criterion with an llm_structured pass/fail evaluator; linear pass-routing (on_yes: verify-criterion-<N+1> or done; on_no: failed). - mode: adversarial — three probe states (probe-boundary, probe-malformed-hostile, probe-failure-mode) with llm_structured evaluators; a count_probes shell gate with output_numeric ≥ 3; terminals: done, failed_with_finding, failed_too_few. FAIL fires when fewer than 3 probe classes are genuinely attempted, even if every attempted probe passed.

Usage:

/ll:verify-issue-loop FEAT-919
/ll:verify-issue-loop FEAT-919 --mode adversarial

See also: /ll:create-eval-from-issues, /ll:create-loop, /ll:go-no-go

/ll:loop-suggester

Analyze user message history to suggest FSM loop configurations automatically.

Arguments: - file (optional): Path to ll-messages JSONL file (runs extraction if omitted) - --from-commands (optional flag): Analyze the command/skill catalog instead of message history — works on fresh installations with no session history - --from-sequences [path] (optional flag): Analyze ll-logs sequences n-gram output instead of message history — maps repeated command chains to loop paradigms; falls back to message-history path if sequences output is empty

Features: - Detects repeated tool sequences (check-fix cycles, multi-constraint patterns) - Maps patterns to appropriate loop types (fix-until-clean, maintain-constraints, drive-metric, run-sequence) - Generates ready-to-use loop YAML with confidence scores - Outputs to .ll/loop-suggestions/

Usage:

# Analyze recent messages (auto-extracts)
/ll:loop-suggester

# Analyze specific JSONL file
/ll:loop-suggester messages.jsonl

# Suggest loops from available commands/skills catalog (no history required)
/ll:loop-suggester --from-commands

# Suggest loops from ll-logs sequences n-gram output (telemetry-driven)
/ll:loop-suggester --from-sequences

# Suggest loops from a saved sequences JSON file
/ll:loop-suggester --from-sequences .ll/sequences-2026-06-13.json

Trigger keywords: "suggest loops", "loop from history", "automate workflow", "suggest loops from commands", "loop from catalog", "suggest loops from sequences", "from-sequences", "loop from ll-logs"

/ll:review-loop

Review an existing FSM loop configuration for quality, correctness, consistency, and potential improvements. Analyzes all states and transitions, runs behavioral verification via ll-loop simulate, reports findings by severity (Error/Warning/Suggestion), proposes concrete fixes with before/after diffs, applies approved changes, and persists a review artifact to .loops/reviews/<name>-<YYYYMMDD-HHMMSS>.md.

Arguments: - loop_name (optional): Name or path of the loop to review. If omitted, lists available loops to pick from.

Flags: - --auto: Apply all eligible non-breaking fixes automatically. Still prints the full report. - --dry-run: Report findings and scorecard only. Make no changes, skip artifact persistence. - --exercise: In Step 2.5, also run ll-loop run --max-iterations 1 in addition to ll-loop simulate. - --no-simulate: Skip behavioral verification (Step 2.5) entirely. - --rubric-only: Stop after displaying the rubric scorecard. No fix proposals, no artifact persistence. - --strict-semantic: Run SR-* semantic checks in a fresh context seeded only with calibration examples from reference.md to prevent static-check findings from biasing judgment.

Workflow phases:

Step	Phase	Description
1.5	Description gate	Draft description: from FSM structure if absent/< 5 words; unblocks SR-1/SR-4
2a	Validation	Run ll-loop validate; surface V-* findings
2b	Quality checks	QC-1 through QC-14, FA-1 through FA-6
2c	Semantic review	SR-1 through SR-4, FSM Flow Review narrative
2.5	Behavioral verification	ll-loop simulate → SIM-1/SIM-2/SIM-3 checks
3	Display findings	Findings table + FSM Flow Review + 6-dimension rubric scorecard
4	Propose fixes	Interactive or --auto fix application
4.5	Post-fix iteration	Re-run checks after fixes; surface RT-1 for regressions; max 3 rounds
5	Validate and save	ll-loop validate after changes; restore on failure
6	Summary	Findings count, fixes applied, pass/fail status
6.5	Persist artifact	Write .loops/reviews/<name>-<timestamp>.md with frontmatter + diffs

Simulation checks (SIM-*):

Check	Severity	Trigger
SIM-1	Warning	Simulation stalls — repeated state in States visited: before max_steps
SIM-2	Warning	Terminal reached in <2 iterations on a max_steps > 5 loop (no-op happy path)
SIM-3	Error	Simulation hit max_steps without reaching a terminal state

Semantic flow checks (SR-*): In addition to structural (V-, QC-) and flow (FA-*) checks, the skill performs four semantic checks against the declared loop goal:

Check	Severity	Description
SR-1	Warning	Happy-path does not plausibly accomplish the declared goal (skipped if goal is absent or < 5 words)
SR-2	Suggestion	State name implies a narrow gate (check_*, verify_*) but action text is broad analysis, or vice versa
SR-3	Warning	on_yes routes backward to an earlier happy-path state (success routing backward is almost always a logic error)
SR-4	Warning	A key activity phrase from the declared goal has no corresponding state name or action text

SR- findings are listed alongside FA- findings in the Issues section of the output. The FSM Flow Review and Semantic Flow Review output blocks are always emitted, even when all finding counts are zero.

Rubric scorecard: After findings, the skill rates 6 dimensions (Clarity, Decomposition, Resilience, Observability, Idempotence, Cost-Efficiency) on a 1–5 scale for a composite score /30. When a prior .loops/reviews/<name>-*.md artifact exists, trend arrows (↑/↓/→) are shown. See skills/review-loop/reference.md Rubric Dimensions for full scoring criteria.

Review artifact: Persisted to .loops/reviews/<name>-<YYYYMMDD-HHMMSS>.md with YAML frontmatter (loop, reviewed_at, scorecard, findings_count, simulation_result, fixes_applied) and body sections (findings table, rubric justifications, simulation summary, fix diffs). See skills/review-loop/reference.md Review Artifact Schema.

See also: /ll:create-loop, ll-loop validate, ll-loop show, ll-loop simulate

/ll:simplify-loop

Refactor an existing FSM loop into fewer, more readable, more reusable units without changing its behavior. Applies two behavior-preserving transforms:

1. Flow collapse — collapses a linear chain of states (each unconditionally next:-ing the following one) into a flow: list + state_defs: bodies. The resolve_flow() parser expands it back into an identical states: map.
2. Sub-loop extraction — extracts a cohesive region (one entry, clean success/failure exits) into a separate child loop invoked via loop: + with: + on_success/on_failure/on_error.

Arguments: - name (optional): Loop to simplify. If omitted, lists available loops and prompts for selection.

Flags: - --dry-run — Detect and report candidates only; make no changes - --auto / --yes — Skip per-change approval prompts (still validates) - --flows-only — Only apply flow collapse; skip sub-loop extraction - --subloops-only — Only apply sub-loop extraction; skip flow collapse

Trigger keywords: "simplify loop", "decompose loop into sub-loops", "collapse state chain", "extract sub-loop", "refactor loop"

See also: /ll:create-loop, /ll:review-loop, /ll:rename-loop

/ll:debug-loop-run

Analyze loop execution history to synthesize actionable issues from fault signals (BUG-class anomalies that broke the run) and effectiveness signals (ENH-class observations that the run completed but did not do useful work). Auto-selects the most recently interrupted/failed loop, or analyzes a named loop when specified.

Arguments: - loop_name (optional): Loop name to analyze. If omitted, auto-selects the most recently updated interrupted/failed loop. - tail (optional): Limit history events analyzed to the N most recent (default 200) - --skip-issue-creation (flag): Skip issue creation entirely and exit cleanly after presenting signals - --auto (flag): Non-interactive mode; suppress all AskUserQuestion calls and default to no for issue creation (implies --skip-issue-creation). Also activates when --dangerously-skip-permissions is in effect, or when either the LL_NON_INTERACTIVE or DANGEROUSLY_SKIP_PERMISSIONS environment variable is set — each is an independent trigger, and host_runner.py injects both into every host CLI invocation, so auto mode is always on inside ll-auto / ll-parallel / ll-sprint / FSM loop runs.

Signal detection rules:

Fault Signals (BUG-class — broke the run): - Action exit_code ≠ 0 repeated 3+ times on same state → BUG P2 - loop_complete.terminated_by == "signal" (SIGKILL) → BUG P2 - loop_complete.terminated_by == "error" AND no evaluate.verdict == "error" in run (FATAL_ERROR catch-all) → BUG P2; the crash reason is available directly on loop_complete.error (primary) — no forensics required - Last evaluate before loop_complete has verdict == "error" (single occurrence — no threshold) → BUG — Evaluate error terminated the loop P2; uses error field (falls back to reason) from the failing evaluate event; de-duplicates against FATAL_ERROR when both hold (this signal supersedes) - evaluate.verdict == "fail" 3+ times on same state → BUG P3 - State has loop: set AND on_yes == on_no (config-based, detected from FSM structure) → BUG — Sub-loop verdict discarded P3; child loop result is silently dropped regardless of outcome - rate_limit_exhausted event present on a state (max rate-limit retries burned through) → BUG P3; surfaces upstream rate-limit pressure separate from generic retry loops. rate_limit_waiting heartbeat events in the same window indicate in-progress sleeps contributing to the budget. - throttle_hard or throttle_stop event present on a state → BUG P2; state exceeded tool-call hard_max threshold — add on_throttle_hard routing or reduce scope to prevent hard stops. throttle_warn events in the same window signal the state was already near the limit.

Effectiveness Signals (ENH-class — completed but did not do useful work): - Stub action body in resolved state map (e.g. echo "5" in a score/evaluate state, echo "TODO …", echo "Replace …") → ENH P2; surfaces unimplemented action stubs as a static static_issues entry distinct from the history-driven signal list - loop_complete.iterations == 1 AND no apply/refine/update/write/commit-prefixed state was visited → ENH P3 — likely phantom convergence (Signal 1 — iter-1 convergence without apply) - evaluate state route distribution >95% to a single branch (≥10 evaluations single-run, or ≥20 across 5 most recent runs) → ENH P3 (Signal 2 — degenerate gate) - Downstream state references ${captured.X.output} AND producing state for capture X emits empty/whitespace output in >20% of occurrences (≥3 samples) → ENH P3 (Signal 4 — capture vacuum) - evaluate.type is output_numeric or convergence AND captured value has stddev <1% of mean across ≥3 iterations AND has not crossed evaluate.target → ENH P3 (Signal 5 — numeric trajectory stall) - True retry state (has on_retry/max_retries) entered 5+ times, or retry_exhausted event present → ENH P3; intentional cycling state (no retry config) noted informally unless >20 consecutive re-entries → ENH P4 - Avg action duration ≥ 30s across 3+ samples on same state → ENH P4

Sub-loop visibility: Step 2 uses --resolved --json so states with a _subloop key expose the child loop's resolved state map one level deep. Sub-loop states are classified separately and do not contribute to parent loop event counts.

Output format: Each run begins with an Execution Summary preamble before two grouped signal lists (Fault Signals and Effectiveness Signals); either heading is omitted when its count is zero:

### Execution Summary

**Loop goal**: "<loop description or (no description provided)>"
**Observed path**: <state_1> (×N₁) → <state_2> (×N₂) → ... [terminal | in-progress]
**Goal alignment**: <one-sentence assessment, or "Insufficient description to assess alignment.">

**Cross-signal note**: <adjacent states, signal types, and shared root-cause candidate>
(omitted when no co-occurring adjacent signals are found)

**Pattern note**: <sub-threshold behavioral observation>
(omitted when no sub-threshold patterns are detected)

### Fault Signals (N)

  [1] BUG P2 — <title>
  [2] BUG P3 — <title>
  ...

### Effectiveness Signals (M)

  [1] ENH P2 — <title>
  [2] ENH P3 — <title>
  ...

Usage:

# Auto-select most recent interrupted loop
/ll:debug-loop-run

# Analyze a specific loop
/ll:debug-loop-run issue-fixer

# Limit events analyzed
/ll:debug-loop-run issue-fixer --tail 100

# Headless: skip issue-creation prompt (for loop automation)
/ll:debug-loop-run issue-fixer --skip-issue-creation

# Non-interactive: suppress all prompts (for slash_command invocation)
/ll:debug-loop-run issue-fixer --auto

Trigger keywords: "analyze loop", "loop issues", "loop failures", "loop history issues"

See also: /ll:review-loop, /ll:create-loop, /ll:audit-loop-run, ll-loop history

/ll:audit-loop-run

Audit whether a loop's execution actually achieved its stated goal — checking artifact mutations, threshold contracts, structural defects (phantom convergence, degenerate gates, rubric drift, sub-loop verdict laundering), and producing ranked improvement proposals. Auto-selects the most recent loop if no name is given.

Arguments: - loop_name (optional): Loop name to assess. If omitted, auto-selects the most recently updated loop. - tail (optional): Limit history events analyzed to the N most recent (default: all events; auto-scaled via wc -l on the run archive) - --no-rubric-audit (flag): Skip the LLM rubric-vs-description pass (cost gate) - --skip-issue-creation (flag): Skip issue creation entirely and exit cleanly after presenting proposals - --auto (flag): Non-interactive mode; suppress all AskUserQuestion calls and default to no for issue creation (implies --skip-issue-creation). Also activates when --dangerously-skip-permissions is in effect, or when either the LL_NON_INTERACTIVE or DANGEROUSLY_SKIP_PERMISSIONS environment variable is set — each is an independent trigger, and host_runner.py injects both into every host CLI invocation, so auto mode is always on inside ll-auto / ll-parallel / ll-sprint / FSM loop runs.

Sub-loop visibility: Step 2 uses --resolved --json, making sub-loop states visible under _subloop keys in the FSM output. The Step 8 laundering check (on_yes == on_no on any sub-loop state) now operates on the fully-resolved state map.

Verdict values: | Verdict | Condition | |---------|-----------| | met | Terminal reached AND all threshold contracts verified AND all expected artifact mutations occurred | | phantom | Terminal reached AND claimed success > 0 (or no summary.json) AND (artifacts unchanged OR threshold unverified — only model self-reported) | | honest-failure | Terminal reached AND summary.json present AND claimed success == 0 (implemented: 0, failed: N) AND no artifact mutation — loop truthfully reported failure; root cause is upstream | | partial | Terminal reached AND some but not all contracts satisfied | | degraded | Loop completed but metric trended downward vs baseline |

Output format: Each assessment emits a Goal-vs-Outcome Scorecard followed by ranked improvement proposals:

### Goal-vs-Outcome Scorecard

**Goal**: "<loop description or (no description provided)>"
**Contract**: <threshold keys and values, or "none detected">
**Artifacts checked**: <list of paths and mutation status>
**Phase 1 signals**: <fault signal count, or "none">
**Verdict**: `<met | phantom | honest-failure | partial | degraded>`

**Rationale**: <one paragraph explaining the verdict>

Usage:

# Assess most recent loop
/ll:audit-loop-run

# Assess a specific loop
/ll:audit-loop-run issue-fixer

# Skip rubric audit (faster, lower cost)
/ll:audit-loop-run issue-fixer --no-rubric-audit

# Headless: skip issue-creation prompt (for loop automation)
/ll:audit-loop-run issue-fixer --skip-issue-creation

# Non-interactive: suppress all prompts (for slash_command invocation)
/ll:audit-loop-run issue-fixer --auto

Trigger keywords: "assess loop", "audit loop", "loop effectiveness", "loop goal", "phantom success", "loop artifacts", "did the loop work"

See also: /ll:debug-loop-run, /ll:review-loop, /ll:create-loop

/ll:cleanup-loops

Find stuck or stale ll-loop processes, diagnose root causes from state and events files, and clean them up after user confirmation.

Arguments: - --dry-run (flag): Preview discovered stuck/stale loops without making any changes - --threshold N (optional): Minutes before a "running" loop's updated_at is considered stale (default: 15) - --interrupted-age H (optional): Hours before an interrupted loop's updated_at makes it eligible for cleanup (default: 24)

What it does: 1. Runs ll-loop list --all-runs --json to enumerate all loops with state files 2. Checks each loop's PID liveness and updated_at staleness 3. Classifies loops: stuck-running, stale-interrupted, abandoned-handoff, terminal, or healthy 4. Prompts user to confirm cleanup of actionable loops 5. Calls ll-loop stop for stuck-running loops and for stale-interrupted loops whose lock-file PID is still alive (orphaned lock holder blocking scope); removes the artifact file directly for stale-interrupted loops with a dead PID 6. Tails the events file to surface root cause for each cleaned loop

Usage:

# Discover and clean all stuck/stale loops (with confirmation)
/ll:cleanup-loops

# Preview what would be cleaned without making changes
/ll:cleanup-loops --dry-run

# Use a custom staleness threshold (30 minutes)
/ll:cleanup-loops --threshold 30

Trigger keywords: "cleanup loops", "stuck loops", "clean loops", "stale loops", "kill stuck loops"

See also: /ll:debug-loop-run, /ll:review-loop, ll-loop stop, ll-loop monitor

/ll:rename-loop

Rename a loop (built-in or project-level) and update every reference to it so the loop system remains fully functional.

Arguments: - old_name (required): Current loop name (bare identifier, no .yaml extension) - new_name (required): New loop name (kebab-case identifier; may include a sub-directory prefix like oracles/name) - --dry-run (flag): Preview all changes without applying them - --yes (flag): Skip the confirmation prompt

What it does: 1. Locates the loop file in .loops/ (project) or scripts/little_loops/loops/ (built-in) 2. Renames the YAML file and updates its internal name: field 3. Updates all loop: sub-loop references in other YAML files 4. For built-in loops, updates tests and docs references 5. Confirms the change plan before applying (unless --yes is set)

Usage:

/ll:rename-loop fix-types fix-quality-and-tests
/ll:rename-loop old-loop-name new-loop-name --dry-run   # preview only
/ll:rename-loop old-name new-name --yes                 # skip confirmation

Trigger keywords: "rename loop", "rename a loop", "change loop name"

See also: /ll:create-loop, /ll:review-loop, ll-loop show

/ll:distill-traces

Mine loop execution history in .loops/.history/ to extract reusable state templates and transition patterns, then write them as fragment library files under scripts/little_loops/loops/lib/<loop-name>/.

Arguments: - loop_name (required): Name of the loop whose history to distill

Output files written to scripts/little_loops/loops/lib/<loop-name>/: - state-templates.yaml — state definitions ranked by success frequency - transitions.yaml — transition patterns with guard conditions - primitives.md — concise human-readable catalogue of extracted primitives

Usage:

/ll:distill-traces rn-plan
/ll:distill-traces autodev

Trigger keywords: "distill traces", "extract fragments", "mine loop history", "loop primitives", "state templates from history"

See also: /ll:create-loop, /ll:review-loop, ll-loop fragments

/ll:workflow-automation-proposer

Synthesize workflow patterns into concrete automation proposals. Final step (Step 3) of the /ll:analyze-workflows pipeline.

Arguments: - step1_file step2_file (optional): Paths to step 1 and step 2 YAML files (auto-detected if omitted)

CLI fallback: ll-workflows propose --patterns step1.yaml --workflows step2.yaml runs the same Step 3 logic directly from the command line, making the full pipeline scriptable end-to-end without an interactive Claude Code session. See CLI reference for flags.

---

Quick Reference

Command	Description
init^	Initialize project configuration
help	Show command help
configure^	Interactive configuration editor
toggle-autoprompt	Toggle automatic prompt optimization
check-code	Run lint, format, type checks
run-tests	Execute test suites
find-dead-code	Identify unused code
explore-api^	Explore external API/library behavior and record proof to Learning Test Registry
capture-issue^	Capture issues from conversation or description
format-issue^	Format issue files (interactive or --auto mode)
scan-codebase	Find issues in code (technical analysis)
scan-product	Find issues in code (product-focused analysis)
product-analyzer^	Analyze codebase against product goals for feature gaps
prioritize-issues	Assign P0-P5 priorities
ready-issue	Validate and fix issue files
verify-issues	Check issues against code
align-issues	Validate issues against key documents
normalize-issues	Fix issue filenames lacking valid IDs
sync-issues	Sync local issues with GitHub Issues
manage-issue^	Full issue lifecycle management
iterate-plan	Update implementation plans
confidence-check^	Pre-implementation confidence check for readiness
spike^	Prove an unproven internal mechanism with an isolated code spike before implementing
refine-issue	Refine issues with codebase-driven research
decide-issue^	Resolve competing implementation options via codebase evidence scoring
wire-issue^	Complete integration map — trace callers, config, docs, tests
reconcile-issue	Rewrite stale Implementation Steps/AC/Files to Modify (plus contradicted Scope Boundaries claims) from an issue's own findings
tradeoff-review-issues	Evaluate issues for utility vs complexity
issue-workflow^	Quick reference for issue management workflow
issue-size-review^	Evaluate issue size/complexity and propose decomposition
map-dependencies^	Analyze cross-issue dependencies based on file overlap
audit-issue-conflicts^	Scan open issues for conflicting requirements and architectural decisions
link-epics^	Assign parentless open issues to open epics, or synthesize new EPICs from them, via similarity scoring
go-no-go^	Adversarial go/no-go debate for issue implementation decisions
advise^	One-shot, signal-cited consult to a different (typically stronger) model
audit-architecture	Analyze code structure
audit-docs^	Check documentation accuracy
update-docs^	Identify stale or missing docs from recent commits and completed issues
audit-claude-config^	Comprehensive config audit
improve-claude-md^	Rewrite CLAUDE.md with <important if> blocks for scoped instruction attention
analyze-workflows	Analyze user message patterns for automation
analyze-history^	Analyze issue history for project health and trends
commit	Create git commits (supports --auto for non-interactive use)
describe-pr	Generate PR descriptions
open-pr	Open a pull request for current branch
cleanup-worktrees	Clean up stale worktrees and branches
manage-release	Manage releases, tags, and changelogs
update^	Update little-loops plugin and package (consumer-first)
publish (project-local)	Bump version in all source files (maintainers only — .claude/commands/publish.md, not shipped)
handoff	Generate session handoff prompt
resume	Resume from continuation prompt
create-loop^	Interactive FSM loop creation
create-eval-from-issues^	Generate eval harness YAML from issue IDs
verify-issue-loop^	Generate verification loop YAML from a single issue's acceptance criteria (--mode criteria\|adversarial)
loop-suggester	Suggest loops from message history
review-loop^	Review and improve existing FSM loop configurations
simplify-loop^	Refactor a loop: collapse linear state chains to flows, extract sub-loops — behavior-preserving
debug-loop-run^	Analyze loop execution history: synthesizes an Execution Summary (goal alignment, observed path) and extracts actionable issues from fault and effectiveness signals
audit-loop-run^	Audit loop goal achievement: checks artifact mutations, threshold contracts, phantom convergence, and produces ranked improvement proposals
cleanup-loops^	Find and clean stuck or stale loop processes
rename-loop^	Rename a loop and update all references
workflow-automation-proposer^	Synthesize workflow patterns into automation proposals
distill-traces^	Mine loop execution history to extract reusable state templates and transition patterns
create-sprint	Create sprint with curated issue list
review-sprint	Review sprint health and suggest improvements
review-epic^	Audit EPIC health: stalled children, scope drift, missing coverage
scope-epic^	Decompose a theme into an EPIC with 3–8 pre-wired child issue stubs

---

Common Workflows

# Get started with a new project
ll-init

# Run all code quality checks
/ll:check-code

# Find and fix issues automatically
/ll:scan-codebase            # Technical analysis
/ll:scan-product             # Product analysis (if enabled)
/ll:normalize-issues
/ll:prioritize-issues
/ll:format-issue --all --auto  # Auto-format all issues (template v2.0 alignment)
/ll:manage-issue bug fix

# Prepare for a pull request
/ll:run-tests all
/ll:check-code
/ll:commit
/ll:open-pr