SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsconstraints-extractor

constraints-extractor

Security & auditing

View repository

Updated 10-15 21:53

About this skill

Constraints Extractor

Extract explicit and implicit constraints from project documentation and synthesize them into a canonical CONSTRAINTS.md — a living record of the externally-imposed boundaries (compliance, security, hosting, tooling, stakeholder, scope, dependency) that shape what a project can build and how.

Relationship to Other Living Documents

This skill is deliberately narrow. If a piece of content isn't clearly a constraint, it stays out of this file. Apply the forcing-function test before writing anything down:

Forcing-function test: if this were ignored, would something break OUTSIDE
the codebase — a contract, a law, a security posture, an executive decision,
a vendor relationship? If yes, it's a constraint.

If the honest answer is "the team would just be inconsistent" or "it would look different," it's a pattern or a procedure, not a constraint — it belongs in config.yaml or AGENTS.md instead.


| Document | Produced by | Captures |
| --- | --- | --- |
| `openspec/config.yaml` | `onboard-openspec` skill | WHAT the team chose (stack, patterns) |
| `AGENTS.md` / `CLAUDE.md` | `onboard-agent` skill | HOW the agent should behave |
| `ARCHITECTURE.md` | `architecture-doc` skill | HOW the system is structured today |
| `CONSTRAINTS.md` | **this skill** | WHY certain choices are non-negotiable |

Full category definitions, the forcing-function test worked through in
detail, and an in-scope/out-of-scope example table per category live in
`references/category-guide.md` — read it before running per-document extraction.

## Output Location

Determine where `CONSTRAINTS.md` belongs before scanning anything, so
Source Discovery knows to treat an existing file as authoritative rather
than as scan fodder.

1. Search the repository for an existing `CONSTRAINTS.md` file before doing
   anything else. Use a repo-wide search (`find`, `rg`, or equivalent), not a
   narrow check of only the root or `docs/`. If exactly one exists, that is the
   target — use it, don't ask.
2. If more than one `CONSTRAINTS.md` exists, stop and show the matches. Ask the
   user which one is authoritative rather than guessing.
3. If nothing exists, default to `CONSTRAINTS.md` at the repo root, alongside
   `ARCHITECTURE.md` and `AGENTS.md`.
4. Announce the chosen path before proceeding: *"No existing
   CONSTRAINTS.md found — I'll write to ./CONSTRAINTS.md."*

## NEVER Do When Extracting Constraints

- **NEVER invent a constraint not supported by evidence in a source
  document.** If a candidate statement doesn't have real evidence behind
  it, it doesn't qualify as `CONFIRMED` — treat it as a near-miss instead
  (see "Preview Before Writing" below), not a low-confidence entry. There
  is no third tier to fall back on for weak evidence.
- **NEVER silently drop a constraint because sources conflict.** Record both
  sides, mark the entry `CONFLICTING`, and cite each source.
- **NEVER write a constraint without at least one evidence citation** (file
  plus section or line reference). An unsourced constraint reads the same
  as a hallucinated one.
- **NEVER treat a confidently-worded team preference as a constraint.** Apply
  the forcing-function test. If no external force is evident, surface it in
  the pre-write preview as a near-miss and leave it out of the file — see
  "Preview Before Writing" below.
- **NEVER write a "Reviewed, Not Included" section, or any section like
  it, into `CONSTRAINTS.md`.** Near-misses are conversation output, not
  file content — see "Preview Before Writing."
- **NEVER add a "Related Documentation" section to `CONSTRAINTS.md`.** The
  linking is one-directional: `AGENTS.md` or `CLAUDE.md` point to this file via the cross-link step, not the other
  way around. A reverse pointer back to files that already reference this
  one is pure noise.
- **NEVER write a scratch or findings JSON file anywhere inside the
  repository being scanned, and never with a relative filename.** Every
  intermediate file — each subagent's scratch output and the single
  correlated findings file — lives under an absolute
  `/tmp/constraints-extractor.XXXXXX/` path. A relative filename resolves
  against the agent's working directory, which is the repo being scanned,
  not `/tmp`.
- **NEVER hand-write or hand-format an entry in `CONSTRAINTS.md`.** Every
  new or corroborated entry — including a single new entry — goes
  through `scripts/merge_constraints.py`. Hand-formatting is how
  inconsistent structure (ad hoc symbols, extra fields, uneven spacing)
  ends up in the file, and it breaks the script's ability to parse the
  file back in on the next run.
- **NEVER expect `scripts/merge_constraints.py` to remove a stale entry
  or replace a bad citation on its own.** The script is additive by
  design — it inserts new findings and corroborates existing ones by
  merging evidence, but it has no delete path, even when a fresh scan
  directly contradicts an existing `CONFIRMED` entry (that case becomes a
  `CONFLICTING` finding, which still *adds* claims rather than removing
  the original). Removing a stale entry or fixing a bad citation is the
  one case where a direct, confirmed edit to `CONSTRAINTS.md` is
  correct — see "Removing Stale Entries and Bad Citations" below for the
  exact procedure. That is not a loophole in the rule above: it's
  correcting existing, already-correctly-formatted lines under explicit
  user confirmation, never inventing new ad hoc structure.
- **NEVER crawl `openspec/changes/archive/` automatically** — it grows too
  large for a full-corpus scan and drowns real signal in resolved-change
  noise. Only read specific archive files if the user names them explicitly.
- **NEVER run subagent extraction serially when subagents are available** —
  dispatch in parallel, capped at 5 concurrent subagents. More than 5
  source documents means multiple waves, not unlimited concurrency.
- **NEVER overwrite an existing `CONSTRAINTS.md` without reading it first**
  — a human may have hand-corrected a confidence rating or resolved an
  ambiguity that a fresh scan can't recover.

---

## Source Discovery

Before spawning any subagents, assemble the set of source documents to scan.
Announce the final list to the user before dispatching subagents.

**Step 1 — Auto-discover conventional locations.** Check for, and if
present, include:

- `docs/`, `documents/`, `doc/` (recursively — markdown and plain text)
- `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `COMPLIANCE.md`, `LICENSE*`
- `ARCHITECTURE.md`, `AGENTS.md` / `CLAUDE.md`, `openspec/config.yaml` —
  these are decision *outputs*, but their prose sometimes carries buried
  rationale that never got promoted to a first-class constraint
- Decision-record style folders, if present: `adr/`, `decisions/`, `rfd/`,
  `rfcs/`, `notes/`, `spikes/` — any folder holding NOTE/SPIKE/RFC-style
  documents is high-signal, since rationale for a resolved decision is
  exactly where a forcing function tends to get written down explicitly
- An existing `CONSTRAINTS.md` at the location determined in "Output
  Location" above, if one exists (read it fully — see "Locate or Create
  CONSTRAINTS.md" below, do not treat it as just another scan target)

Run every check above as **one consolidated bash command**, not a
separate tool call per path — these are all fast existence checks with no
reasoning involved, so batching them costs one round trip instead of a
dozen:

```bash
for p in docs documents doc README.md CONTRIBUTING.md SECURITY.md \
         COMPLIANCE.md ARCHITECTURE.md AGENTS.md CLAUDE.md \
         openspec/config.yaml adr decisions rfd rfcs notes spikes; do
  [ -e "$p" ] && echo "FOUND: $p"
done
ls LICENSE* 2>/dev/null

Step 2 — Accept an explicit user-provided list. If the user names specific files or paths — including files inside openspec/changes/archive/ — add them to the set. This is additive to Step 1, never a replacement for it.

Step 3 — Deduplicate and announce.

Merge (Step 1 ∪ Step 2) by resolved path, then tell the user:

"Scanning N documents across ceil(N/5) waves of up to 5 subagents each:
[list]. This excludes openspec/changes/archive/ by default since it's
typically too large for a full pass — name specific files there if you
want them included."

If the merged set is empty, stop and ask the user where their documentation lives rather than guessing at paths.

Per-Document Extraction (parallel subagents)

Spawn one subagent per source document — parallel, never serial, capped at 5 concurrent subagents. With more than 5 documents in the discovered set, dispatch in waves of up to 5: wait for a wave to finish before starting the next.

Waves are a dispatch-batching concern only. They do not change the Single Correlation Pass below — that still runs exactly once, after every wave has finished, never once per wave.

Each subagent:

  1. Reads its assigned file in full.
  2. Applies the forcing-function test to every rule, limit, or boundary statement it finds.
  3. For each candidate constraint, extracts:
    • statement — the constraint in plain English, self-contained (must read correctly without the source file open)
    • impact — one to three sentences on practical impact: what this constrains, what decisions it should shape, what breaks if ignored. Required whenever a constraint is included. If a subagent can't articulate this, that's usually a sign the candidate is a near-miss, not a real constraint.
    • category — the exact slug, verbatim: compliance-governance, security-privacy-ip-cui, hosting-infrastructure, tooling-approved-path, workflow-sequencing, stakeholder-executive, scope-prioritization-delivery, or external-dependencies. Full definitions in references/category-guide.md. Use the slug itself, not a shortened or display form of it — merge_constraints.py will auto-correct a few common variants but hard-fails on anything it can't confidently resolve, and a mismatch here is how a category's findings silently go missing.
    • confidence — always CONFIRMED at this stage. There is no "weak evidence" tier — if the statement isn't backed by a real citation, it's a near-miss, not a lower-confidence constraint. CONFLICTING only gets assigned during the Single Correlation Pass below, when two extracted findings disagree; a single-document subagent can't see that on its own.
    • evidence — a list of citations, each with file (relative path from the project root, not an absolute path), location (a line number or range where the source has real line numbers, a short section anchor otherwise), and note (one required sentence on what that specific citation shows — this becomes the entry's Evidence notes bullet for that citation, so it needs to earn its own line, not just restate the statement).
    • affects — optional list of bare tokens (rule IDs, other constraint IDs, system names) this constraint's enforcement touches. Omit or leave empty rather than guessing at a token that isn't actually named in the source.
    • enforced_by — optional list of bare tokens naming a specific downstream rule (in AGENTS.md, ARCHITECTURE.md, config.yaml, or elsewhere) that this constraint drives. Omit rather than guessing.
  4. Also flags near-miss candidates — statements that read like constraints but fail the forcing-function test — with a one-line reason. These are surfaced only in the pre-write preview (see "Preview Before Writing") and are never written into CONSTRAINTS.md itself.
  5. Writes full findings as JSON to a scratch file at an absolute path under mktemp -d "/tmp/constraints-extractor.XXXXXX" (one file per subagent — never a relative filename, never anywhere inside the repository being scanned) and returns only a one-line confirmation to the orchestrator, e.g. Extracted 4 constraints, 2 near-misses from docs/SECURITY.md. Keep bulk findings out of the orchestrator's context — the orchestrator reads scratch files directly during the single correlation pass; it does not receive findings inline.

Never assign an entry's CONSTR-<CATEGORY>-<NNN> ID at this stage, or at correlation — ID assignment happens once, inside merge_constraints.py, scoped per category. Extraction and correlation only ever produce findings; the script is the sole owner of identity.

Single Correlation Pass

After all subagents complete, run exactly one reduce pass — never one per wave.

  1. Read every scratch file in one call — cat /tmp/constraints-extractor.XXXXXX/*.json — rather than opening each one with a separate tool call.
  2. Group candidates by category.
  3. Correlate duplicates. If two or more sources support the same underlying constraint, merge into a single finding, combining their evidence citations (deduped by file+location, not summed) into one evidence list. Every citation keeps its own note — merging findings doesn't merge notes into one another.
  4. Surface conflicts. If two sources make incompatible claims about the same boundary, do not pick a winner. Build a claims list — one entry per side, each with its own statement, file, and location — set confidence to CONFLICTING, and drop the evidence/impact fields for that finding entirely (a CONFLICTING finding carries claims instead, never both).
  5. Route near-misses. Anything flagged as a near-miss during per-document extraction is carried into the correlated findings file for the preview step to display — it does not get a section in CONSTRAINTS.md.

Write the correlated result to <scratch-dir>/correlated-findings.json — an absolute path in the same /tmp directory as the scratch files, never a bare relative filename. The top-level shape is a flat list, not a grouping by category:

{"constraints": [ {"category": "workflow-sequencing", "title": "...", ...}, ... ], "near_misses": [...]}

Not {"workflow-sequencing": [...], "compliance-governance": [...]}. The merge script reads the constraints array and reads each item's own category field — it does not know how to interpret category names used as top-level JSON keys. It checks for the constraints key explicitly and refuses to run if it's missing, naming the keys it actually found, so this shows up as a clear error rather than a silent zero-result write. See references/troubleshooting.md for the full shape the merge script expects (only needed if you're troubleshooting the merge step; day-to-day use doesn't require reading it).

Locate or Create CONSTRAINTS.md

Use the path determined in "Output Location" above.

  • If it exists: read it fully first. Treat any hand-edited entry as authoritative over a fresh scan's version of the same constraint, unless new evidence directly contradicts it — in that case, flag the conflict in the preview step rather than overwriting silently. Merge new findings into the correct category sections in place.
  • If it doesn't exist: create it fresh from references/template.md.

All mechanical file operations for additions and corroboration — ID assignment, category insertion, dedup merge, ordering — are handled by scripts/merge_constraints.py. Never hand-edit the file's structure with ad hoc string appends; naive end-of-file appending corrupts category grouping. The script is the single source of truth for how new or corroborated entries get inserted. It cannot remove an entry or a citation — see "Removing Stale Entries and Bad Citations" below for the one case where editing the file directly is correct instead:

python3 scripts/merge_constraints.py \
  --target <absolute path to CONSTRAINTS.md> \
  --findings <absolute path to correlated-findings.json under /tmp>

Both arguments must be absolute paths. The script refuses to run with a relative --findings path, precisely because a relative path resolves against the repo being scanned rather than /tmp.

The script is idempotent — re-running it with the same findings file produces no diff.

A finding that fails validation (bad category, missing evidence, an unrecognized shape it can't coerce) is skipped individually — it does not block the rest of the batch from being written. Check the script's stdout after every run: it reports both what was written and what was skipped, with the specific reason for each skip. Relay skipped findings back to the person rather than treating a successful exit as "everything from this run made it in" — a partial write is still a successful run.

Removing Stale Entries and Bad Citations

merge_constraints.py is additive only: it inserts new findings and corroborates existing ones by merging evidence, but it has no delete path. It will never remove an entry, drop a citation, or replace one that's gone bad, even when a fresh scan directly contradicts an existing CONFIRMED entry — that case becomes a CONFLICTING finding, which still adds claims rather than removing the original. If removal or a citation fix is what's actually needed, running the script again with new findings will not produce it.

Two situations call for this instead of a normal merge run:

  • A stale entry. The constraint no longer holds — the source document was rewritten, the policy changed, the vendor relationship ended — and nothing in a fresh findings file will ever supersede it, because the script only matches on category + title and has nothing to match against for "this no longer applies."
  • A bad citation. The file:location on an existing entry no longer points to the text it once did (the file moved, the section was rewritten, the line numbers shifted), so the entry's evidence silently stops backing its own statement.

Handle either the same way as any other change to the file: surface it in "Preview Before Writing" below with the reason, get the user's confirmation, then make the edit by hand — run merge_constraints.py first for whatever additions or corroboration the same pass produced, and make the manual cleanup edit afterward, so the script's parse-and-render pass isn't reparsing a file mid-edit.

"By hand" means correcting or deleting existing, already-correctly- formatted lines per references/entry-format.md — never freeform reformatting, and never an excuse to hand-write a new entry while you're already in the file:

  • Removing an entry entirely: delete the whole `### CONSTR- ·
  • Fixing one bad citation on an entry that otherwise still holds: edit only that citation's segment in the Evidence: line (and its (N refs) count if the citation is being dropped rather than corrected) and the matching bullet under Evidence notes: — same position in both lists, per the field rules in references/entry-format.md. Leave every other field on the entry untouched.

This is the one place in this skill where editing CONSTRAINTS.md directly is correct instead of a validation workaround: the "never hand-write an entry" rule above exists to stop ad hoc structure from creeping in, not to freeze the file against a human-confirmed correction the script has no mechanism to make itself.

Preview Before Writing

Show the user a summary before touching the filesystem:

  • New constraints found, grouped by category
  • Constraints whose evidence ref count grew via corroboration from multiple sources
  • Any CONFLICTING entries, with every claim shown side by side
  • Near-misses found, with their one-line reasons — shown here only; they are never written into CONSTRAINTS.md
  • Stale entries or bad citations found during this run, flagged for removal or correction, with the reason for each — see "Removing Stale Entries and Bad Citations" above. These need the same explicit confirmation as everything else here, since merge_constraints.py cannot act on them and the only path is a direct, hand-confirmed edit.

Ask: "Does this look right? Anything to reclassify, merge, or drop before I write it?"

A wrong compliance boundary is worse than a wrong reference doc entry elsewhere — do not skip this step even for small diffs. If a run produces zero new constraints, say so plainly rather than padding the file to look productive.

Cross-Link From the Agent Behavior File

If AGENTS.md or CLAUDE.md exist at the project root, check whether the target already has a "Related Documentation" section referencing CONSTRAINTS.md. If not, offer to append a reference.

The constraints are only useful to future agent runs if something points them at it. CONSTRAINTS.md itself should stay a pure list, it should not reference agent behavior files, but the reverse should hold: AGENTS.md or CLAUDE.md, if either exists, should reference the constraints file so a later agent working in this project picks it up as context.

Check, in order, whether ./AGENTS.md or ./CLAUDE.md exists at the project root. If ./CLAUDE.md exists but its content is just an import pointer to AGENTS.md (for example, the file's content is essentially just @AGENTS.md), and ./AGENTS.md exists too, treat AGENTS.md as the real target instead of editing the pointer file. If neither file exists, skip this step; do not create one from scratch, that is out of scope for this skill.

If a target file was found, read it fully first, then:

  • If it already has a ## Related Documentation section, check whether the constraints file is already listed there (search for its path, or CONSTRAINTS.md). If it is, leave the file alone. If not, add one entry to that section, preserving every existing entry exactly as it was.
  • If no such section exists, add one at the end of the file.

Either way, the entry looks like this, with the constraints's actual path in place of CONSTRAINTS.md:

- **CONSTRAINTS.md** — Externally-imposed boundaries (compliance,
  security, hosting, stakeholder) that shape what this project can build
  and how.
  _(Check this before scoping any change with compliance,
  security, hosting, or stakeholder-priority implications — it is not
  optional background reading)_

Do this with plain prose edits, not a companion script. This is a single one-time presence check per file, not high-volume sorting or deduplication — there's no ongoing mechanical work here that justifies a script.

Reference Files

  • references/category-guide.md — the eight constraint categories, the forcing-function test worked through with examples, and an in-scope vs. out-of-scope table per category. Read before per-document extraction.
  • references/template.md — the bare CONSTRAINTS.md skeleton used for new-file creation. Nothing but the eight category headings — no example content, so it can never be mistaken for real entries on first parse.
  • references/entry-format.md — the CONSTRAINTS.md entry grammar that merge_constraints.py renders and parses. Read once per run.
  • references/troubleshooting.md — the JSON shapes extraction and correlation produce, the shape-tolerance layer, and the merge script's exact behavior. Only needed if a run actually fails.