Dot Scout

Scout

You are analyzing a project to determine which principles apply, creating or updating .principles files to encode that, and generating the review files agents use. Judgement (profiling, placement) is yours; everything mechanical is done by scripts in .agents/principles-catalog/bin/. Follow these six phases exactly.

Shortcuts (check $ARGUMENTS first):

• --explain <path>: run bash .agents/principles-catalog/bin/resolve.sh --format explain <path>, show the output (the active principles for that path and which .principles file added, excluded, locked or waived each one), and stop.
• --yes: skip the confirmation question in Phase 3 and write the proposal as shown. Everything else is unchanged.

Phase 1 - Resolve Target and Check the Catalog

Determine the target directory:

• If $ARGUMENTS is a directory path: use it as the target.
• If $ARGUMENTS is empty (or only --yes): use the current working directory.
• If $ARGUMENTS is a file path: use its containing directory.

Confirm the target exists. If not, report an error and stop.

Walk up from the target to find the git root (directory containing .git/). Record both the target directory and the git root - the hierarchy spans between them.

1.1 - Check the Catalog

Check that .agents/principles-catalog/index.tsv and .agents/principles-catalog/bin/emit.sh exist at the git root.

If either is missing, stop and report:

"⚠️ .agents/principles-catalog/ is missing or out of date. From your dot-principles checkout, run ./install.sh vendor <git-root> and then re-run /dot-scout."

Do not search the file system for install.sh.

1.2 - Load Scout Extensions

Glob .agents/principles-catalog/principles/*/.context-scout.md. Only extra catalogs ship these. For each file found, read it and record the detection rules it defines: { namespace → [detection rules] }. They supplement Phase 2. If there are none, use the built-in detection only.

Phase 2 - Detect Profile

Analyse the target directory (and subdirectories) to build a profile per directory. For each directory, detect:

Code artifact signals

Domain signals (for code artifact type)

Non-code artifact type signals

Extension-based detection

After applying the built-in signals above, apply any detection rules loaded in Phase 1.2. For each rule:

• Check whether the directory (or subtree) matches the rule's file pattern criteria
• If matched: assign the artifact type and add the suggested group to that directory's profile

Per-directory profiling

For projects with multiple subdirectories, detect profiles per directory:

• src/main/ vs src/test/ - different testing principles for test dirs
• src/security/, src/auth/ - security-focused principles
• frontend/, ui/, web/ - UI interaction principles
• docs/, doc/ - documentation principles (@docs)
• infra/, terraform/, k8s/, deploy/ - infrastructure principles (@infra)
• .github/workflows/ - pipeline principles (@pipeline)
• Any directory matching an extension-based detection rule (Phase 1.2) - apply the group from that rule

Record a profile map: { directory → [detected groups] }

Phase 3 - Propose Placements and Confirm

Based on the profile map from Phase 2, propose where to place .principles files and what to put in each. Check exclusion density (3.3) before showing anything, so the user confirms once.

3.1 - Placement strategy

1. Git root .principles: Activate groups that apply to the whole project
2. Subdirectory .principles: Activate additional groups or exclude principles that don't apply to that subtree

List the available groups with ls .agents/principles-catalog/groups/ and reference them by filename without .yaml. The common ones are:

Language groups: java, typescript, python, go, csharp, rust Framework groups: spring-boot, spring-data-jpa, react, angular, django, fastapi Cross-cutting code groups: microservices, security-focused Artifact-type groups: docs, infra, config, schema, pipeline

Custom groups from extra catalogs or an org baseline appear in the same directory. Groups suggested by extension detection rules (Phase 1.2) are included automatically.

If .agents/principles-catalog/org.principles exists, the organization has locked some principles (:lock). Never propose a !ID for a locked principle; if a directory truly needs an exception, propose :waive ID until YYYY-MM-DD "reason" instead and say why.

3.2 - How exclusions work (read before proposing any !)

Files are applied from the outside in, root first. The deepest file that mentions a principle decides: !ID or !@group in an outer file removes it, and an @group or ID in a deeper file adds it back. Inside one file, exclusions win over additions whatever the line order. A principle locked by the organization can never be removed.

Groups overlap: every language group includes source-code, and kotlin includes java. So !@kotlin also removes the shared principles that a Java directory needs. That is safe only when a deeper directory adds them back with its own group (@java in bot-api/java/.principles). Two rules follow:

• Never put !@group and a group that overlaps it in the same file: the exclusion wins and removes the shared principles.
• Put an exclusion in the directory above the ones that add their own group, or keep it out and place the group in each directory that needs it.

3.3 - Exclusion density analysis

Before writing, check whether any parent-level proposals would generate unnecessary exclusions in child directories.

When to run

Only when the profile map from Phase 2 contains two or more directories that would each receive their own .principles file (i.e., there is at least one parent-child pair in the proposed hierarchy). Skip this phase entirely if every proposed .principles file is a leaf with no applicable children.