constraint-discovery_skill

Overview

This skill discovers project constraints by launching five parallel Explore agents to scan code, docs, research outputs, tests, and configuration for limits that reduce an AI agent's degrees of freedom. It aggregates findings into a machine-readable constraint scan so developers and agents know what is off-limits, risky, or requires special handling. The output is NDJSON entries annotated with severity, provenance, and concrete recommendations.

How this skill works

The skill spawns five background Explore agents that each follow a focused checklist: project memory and philosophy, architecture and coupling, research session lessons, testing and validation gaps, and overall degrees of freedom. Each agent recursively follows @-style links across files to ensure deep coverage and emits NDJSON constraint objects. Finally, results are merged into a single constraint scan file for downstream use by automation or human review.

When to use it

• Before an automated agent (Ralph/Claude) performs broad refactors or exploratory changes.
• When you need a defensible list of forbidden patterns, hard gates, or one-way state transitions.
• During planning or PR reviews to identify modules that cannot be safely changed.
• After research experiments to capture abandoned strategies and failure thresholds.
• When preparing release automation that must respect feature flags and validation gates.

Best practices

• Keep CLAUDE.md, ROADMAP.md, and ADRs up to date so the agents discover accurate constraints.
• Standardize @ link patterns and include provenance context to make tracebacks reliable.
• Annotate tests and CI gates with explicit requirements so testing constraints are detectable.
• Record lessons_learned and warnings in research session outputs for reproducible avoidance.
• Review the merged scan file regularly and resolve high/critical constraints before large changes.

Example use cases

• Run a constraint scan before enabling an automated refactoring bot to avoid breaking public APIs.
• Audit a repository to find configuration values, feature flags, or hardcoded limits that block experiments.
• Capture failed experiment boundaries so future runs avoid known-danger hyperparameter regions.
• Identify untested or fragile modules that require additional validation before shipping.
• Generate an operational checklist for an AI assistant to follow safe-change rules during deployments.