/codd-scan

name: codd-scan
description: |
  Refresh a CoDD project's dependency graph from document frontmatter and source code. Use after changes to requirements, design docs, implementation, or tests when the user needs current graph data, frontmatter coverage, node and edge counts, or warnings before validation or impact analysis.

CoDD Scan

Refresh the CoDD dependency graph from document frontmatter and source code so later commands (`codd validate`, `codd impact`, `codd generate`, `codd verify`) operate on current project state. Use this after requirements, design docs, implementation, or tests change.

When to Use

• After editing Markdown files with CoDD frontmatter
• After adding or changing source files that affect dependencies
• Before `codd impact` when you need a fresh graph
• When scan counts look stale or unexpectedly low

Preconditions

1. Resolve the target project root first. Prefer an absolute path when the working directory is ambiguous. 2. Check whether `codd/codd.yaml` exists under that path. 3. If `codd/codd.yaml` is missing, initialize CoDD before scanning:

codd init --project-name "<project-name>" --language "<language>" --dest <path>

4. If `codd` is not on `PATH`, use one of these:

• `pip install codd-dev`
• `.venv/bin/codd scan --path <path>`

Command

Run the scan from anywhere by passing the project root explicitly:

codd scan --path <path>

If you are already at the project root, `codd scan --path .` is sufficient.

What the Scan Does

1. Reads `codd/codd.yaml` 2. Rebuilds auto-generated graph data from project documents and source code 3. Preserves human-authored evidence 4. Prints a short summary of frontmatter coverage and graph size

How to Interpret the Result

Typical output includes:

Scan complete:
  Documents with frontmatter: <count>
  Graph: <nodes> nodes, <edges> edges
  Evidence: <total> total (...)

• `Documents with frontmatter`: how many Markdown documents in configured `doc_dirs` were successfully read as CoDD documents. If this is lower than expected, inspect missing frontmatter or wrong `doc_dirs`.
• `nodes`: the number of tracked artifacts in the graph. In document-centric projects this is usually close to the total number of requirements/design/test artifacts being tracked.
• `edges`: the total number of declared or inferred dependency relationships between those artifacts.
• `orphan nodes`: artifacts that have no surviving dependency relationship. They are often a sign of missing `depends_on`, stale docs, or a document that should be deleted. Some top-level requirements may be intentional exceptions, but unexplained orphans should always be reviewed.
• `WARNING:` lines: scan found suspicious input such as missing frontmatter or design docs with empty dependencies. Treat warnings as a prompt to run `codd validate`.
• `SCAN_ERROR` (if surfaced by your wrapper, report script, or higher-level UI): frontmatter could not be parsed or read cleanly. Treat it as a validation problem and inspect the document with `codd validate --path <path>`.

Recommended Next Actions

Use this decision guide after every scan:

| Condition | Next action | |-----------|-------------| | Scan completed and counts look plausible | Run `codd validate --path <path>` to confirm references and frontmatter integrity | | Scan printed warnings or your tooling reports `SCAN_ERROR` | Run `codd validate --path <path>` immediately and fix the reported documents before moving on | | Orphan nodes are present | Check whether they are intentional. If not, add missing dependency metadata or remove obsolete docs, then rerun `codd scan` and `codd validate` | | You already trust the graph and now need blast-radius analysis for recent changes | Run `codd impact --path <path>` | | You need impact for a specific commit or branch delta | Run `codd impact --diff <git-ref> --path <path>` |

Autonomous Workflow

When using this skill without further user guidance:

1. Confirm the project root and `codd/codd.yaml` 2. If CoDD is not initialized, run `codd init ... --dest <path>` first 3. Run `codd scan --path <path>` 4. Read the summary and warnings 5. Run `codd validate --path <path>` if anything looks wrong, incomplete, or newly changed 6. Run `codd impact --path <path>` only after the graph is fresh and you need downstream impact analysis 7. Report the scan summary in plain language: frontmatter coverage, node count, edge count, warnings, and whether follow-up validation or impact analysis is needed

Troubleshooting

`No such file` or path-related failures

• Verify `<path>` points at the project root, not a subdirectory
• Check that `codd/` exists under the target path
• Retry with an absolute path

`codd: command not found`

• Install the CLI: `pip install codd-dev`
• Or run the virtualenv binary directly: `.venv/bin/codd scan --path <path>`

`Error: codd/ not found` or `codd/codd.yaml not found`

• Initialize CoDD first:

codd init --project-name "<project-name>" --language "<language>" --dest <path>

• Then confirm `codd/codd.yaml` and configured `doc_dirs`/`source_dirs` before scanning again

Frontmatter parse errors or `SCAN_ERROR`

• Run:

codd validate --path <path>

• Fix malformed YAML frontmatter, undefined references, or circular dependencies
• Rerun `codd scan --path <path>` after the validation issues are resolved