Analysis Provenance

Analysis Provenance

Identify code ownership before modifying validators, linters, or tool configurations.

Triggers

• check provenance before modifying
• is this file upstream or local
• who owns this validator
• check code ownership
• analyze provenance

Quick Start

# Check provenance of a single file
python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target .config/markdownlint.json

# Check provenance of a directory
python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target .config/

# JSON output for automation
python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target PSScriptAnalyzerSettings.psd1 --format json

Quick Reference

When to Use

Use this skill before:

• Modifying any validator or linter behavior
• Changing tool configuration files
• Investigating unexpected validation failures
• Updating analyzer settings

Process

graph TD
    A[Target file or directory] --> B["1. Target Resolution<br/>Resolve paths, check exists"]
    B --> C["2. Directory Analysis<br/>node_modules, .venv, vendor,<br/>.gitmodules"]
    C --> D["3. Package Manifest Analysis<br/>package.json, requirements,<br/>lockfiles"]
    D --> E["4. File Header Analysis<br/>First 20 lines: generated<br/>markers, copyright notices"]
    E --> F["5. Provenance Determination<br/>Weight signals, return<br/>category + evidence"]
    F --> G["Decision:<br/>UPSTREAM - configure only<br/>LOCAL - safe to modify<br/>VENDOR - track upstream<br/>UNKNOWN - investigate first"]

Decision Tree

Need to modify a validator/linter?
│
├─ Run: python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target <file>
│
├─ Result: UPSTREAM
│  ├─ Do NOT modify the tool/file directly
│  ├─ Adjust local configuration instead
│  ├─ Check for configuration override options
│  └─ If no override exists, document why the rule is suppressed
│
└─ Result: LOCAL
   ├─ Safe to modify as needed
   ├─ Follow project coding standards
   └─ Test changes before committing

Command Reference

From the repository root, run:

python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target <path> [options]

Anti-Patterns

Verification

After running provenance check:

• Category determined (UPSTREAM/LOCAL/VENDOR/UNKNOWN)
• Evidence provided with signal types
• Recommendation matches category
• Exit code is 0 (successful analysis)

Related Skills

Upstream Indicators

Local Indicators

Vendor Indicators

Check Validator Config (LOCAL)

python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target .markdownlint.json

Provenance Check: .markdownlint.json
====================================
Category: LOCAL
Confidence: HIGH
Evidence:
  - File is under project root
  - File is tracked in git
  - No external package reference found
Recommendation: Safe to modify as needed.

Check External Tool (UPSTREAM)

python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target node_modules/markdownlint-cli2/lib/main.js

Provenance Check: node_modules/markdownlint-cli2/lib/main.js
============================================================
Category: UPSTREAM
Confidence: HIGH
Evidence:
  - Located in node_modules directory
  - Package: markdownlint-cli2@0.12.1 (package.json)
  - npm registry: https://registry.npmjs.org/
Recommendation: Do NOT modify. Configure via .markdownlint.json instead.

JSON Output

python3 .claude/skills/analysis-provenance/scripts/check_provenance.py --target PSScriptAnalyzerSettings.psd1 --format json

{
  "target": "PSScriptAnalyzerSettings.psd1",
  "category": "LOCAL",
  "confidence": "HIGH",
  "evidence": [
    {"signal": "project_root", "value": true},
    {"signal": "git_tracked", "value": true},
    {"signal": "external_package", "value": false}
  ],
  "recommendation": "Safe to modify as needed."
}

Before Modifying Validators

# Check provenance FIRST
python3 .claude/skills/analysis-provenance/scripts/check_provenance.py \
  --target <validator-file>

# If UPSTREAM: adjust config
# If LOCAL: modify file

In Pre-commit Hooks

# Prevent accidental upstream modifications
- id: provenance-check
  name: Provenance Check
  entry: python3 .claude/skills/analysis-provenance/scripts/check_provenance.py
  args: [--target, node_modules, --exit-on-upstream]
  language: python

Timelessness: 8/10

Dependency management and provenance tracking are fundamental software engineering practices. The upstream vs local distinction applies regardless of package manager or language. Configuration over modification is a timeless pattern for external dependencies.