analyze-codebase-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# Analyze Codebase Workflow

Survey an arbitrary repository to auto-detect data flows, file I/O, and script dependencies, then produce a structured annotation plan for manual refinement.

## When to Use

- Onboarding onto an unfamiliar codebase and need to understand data flow
- Starting putior integration in a project that has no PUT annotations yet
- Auditing an existing project's data pipeline before documentation
- Preparing an annotation plan before running `annotate-source-files`

## Inputs

- **Required**: Path to the repository or source directory to analyze
- **Optional**: Specific subdirectories to focus on (default: entire repo)
- **Optional**: Languages to include or exclude (default: all detected)
- **Optional**: Detection scope: inputs only, outputs only, or both (default: both + dependencies)

## Procedure

### Step 1: Survey Repository Structure

Identify source files and their languages to understand what putior can analyze.

```r
library(putior)

# List all supported languages and their extensions
list_supported_languages()
list_supported_languages(detection_only = TRUE)  # Only languages with auto-detection

# Get supported extensions
exts <- get_supported_extensions()
```

Use file listing to understand repo composition:

```bash
# Count files by extension in the target directory
find /path/to/repo -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
```

**Got:** A list of file extensions present in the repo, with counts. Map these against `get_supported_extensions()` to know coverage.

**If fail:** If the repo has no files matching supported extensions, putior cannot auto-detect workflows. Consider whether the language is supported but files use non-standard extensions.

### Step 2: Check Language Detection Coverage

For each detected language, verify auto-detection pattern availability.

```r
# Check which languages have auto-detection patterns (18 languages, 902 patterns)
detection_langs <- list_supported_languages(detection_only = TRUE)
cat("Languages with auto-detection:\n")
print(detection_langs)

# Get pattern counts for specific languages found in the repo
for (lang in c("r", "python", "javascript", "sql", "dockerfile", "makefile")) {
  patterns <- get_detection_patterns(lang)
  cat(sprintf("%s: %d input, %d output, %d dependency patterns\n",
    lang,
    length(patterns$input),
    length(patterns$output),
    length(patterns$dependency)
  ))
}
```

**Got:** Pattern counts printed for each language. R has 124 patterns, Python 159, JavaScript 71, etc.

**If fail:** If a language returns no patterns, it supports manual annotations but not auto-detection. Plan to annotate those files manually.

### Step 3: Run Auto-Detection

Execute `put_auto()` on the target directory to discover workflow elements.

```r
# Full auto-detection
workflow <- put_auto("./src/",
  detect_inputs = TRUE,
  detect_outputs = TRUE,
  detect_dependencies = TRUE
)

# Exclude build scripts and test helpers from scanning
workflow <- put_auto("./src/",
  detect_inputs = TRUE,
  detect_outputs = TRUE,
  detect_dependencies = TRUE,
  exclude = c("build-", "test_helper")
)

# View detected workflow nodes
print(workflow)

# Check node count
cat(sprintf("Detected %d workflow nodes\n", nrow(workflow)))
```

For large repos, analyze subdirectories incrementally:

```r
# Analyze specific subdirectories
etl_workflow <- put_auto("./src/etl/")
api_workflow <- put_auto("./src/api/")
```

**Got:** A data frame with columns including `id`, `label`, `input`, `output`, `source_file`. Each row represents a detected workflow step.

**If fail:** If the result is empty, the source files may not contain recognizable I/O patterns. Try enabling debug logging: `workflow <- put_auto("./src/", log_level = "DEBUG")` to see which files are scanned and which patterns match.

### Step 4: Generate Initial Diagram

Visualize the auto-detected workflow to assess coverage and identify gaps.

```r
# Generate diagram from auto-detected workflow
cat(put_diagram(workflow, theme = "github"))

From pjt222/agent-almanac, MIT.

More from pjt222/agent-almanac