entropy-check
Use when checking doc freshness and computing domain quality grades without making fixes.
How do I install this agent skill?
npx skills add https://github.com/fellowship-dev/dogfooded-skills --skill entropy-checkIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill automates documentation audits and repository health checks by scanning project files and GitHub metadata. It computes quality grades for various domains and updates a tracking file directly on the integration branch using the GitHub Contents API. Security analysis identified a low-severity risk related to indirect prompt injection, as data extracted from repository files is interpolated into shell commands without explicit sanitization.
- Socketwarn
1 alert: gptAnomaly
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Entropy
Sensor. Detect, grade, report. Never fix.
Install via npx:
npx skills add fellowship-dev/dogfooded-skills/skills/ops/entropy-check
When to Use
- Event-driven (PR merge): Triggered after a PR merges. Scans affected domains for doc staleness.
- Weekly cron (full sweep): Runs against each product repo, updates QUALITY_SCORE.md with fresh grades.
- Manual: When you suspect docs have drifted or want a current health snapshot before a refactor.
What It Does
Entropy is a read-only sensor. It computes domain quality grades from mechanical signals:
| Signal | What it measures | Weight |
|---|---|---|
| Doc coverage | Does docs/code-structure.md cover this domain? | Binary |
| Flow coverage | FlowChad flow defined for critical paths? | Binary (frontend repos only) |
| Staleness delta | Days since last code commit vs. last doc update | >30d = stale |
| Open issues | Issues tagged to domain in GitHub | >3 open = signal |
| Test coverage | From coverage report if available | <60% = signal |
| Hookshot coverage | Is doc-coverage.json current vs docs? | Staleness |
Grade scale:
- A — All applicable signals green
- B — 1 applicable signal missing or yellow
- C — 2 applicable signals missing
- D — 3+ applicable signals missing
- F — No docs at all for this domain
Inapplicable signals are excluded from the grade denominator. A repo with 4 applicable signals all passing = grade A.
Instructions
0. Identify Target Repo
REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename $(git remote get-url origin) .git)
ORG=$(git remote get-url origin | sed 's/.*github.com[:/]\([^/]*\).*/\1/')
FULL_REPO="$ORG/$REPO_NAME"
TODAY=$(date +%Y-%m-%d)
Read QUALITY_SCORE.md if it exists — this is the baseline to update.
Read ARCHITECTURE.md if it exists — extract domain list.
If neither exists, infer domains from directory structure (top-level source directories, one domain each).
1. Determine Signal Applicability
Before grading, determine which signals apply to this repo. Record applicability for the report.
Frontend Detection (S2 FlowChad)
HAS_FRONTEND=false
if [ -f "$REPO_ROOT/package.json" ]; then
grep -q '"next"\|"react"\|"vue"\|"angular"\|"svelte"' "$REPO_ROOT/package.json" && HAS_FRONTEND=true
fi
if [ -d "$REPO_ROOT/app" ] || [ -d "$REPO_ROOT/pages" ] || [ -d "$REPO_ROOT/src/components" ]; then
HAS_FRONTEND=true
fi
If HAS_FRONTEND=false: S2 FlowChad is inapplicable — exclude from grade denominator.
Hookshot Detection (S6)
HOOKSHOT_EXISTS=false
git -C "$REPO_ROOT" log -1 --format="%ci" -- .claude/doc-coverage.json 2>/dev/null | grep -q . && HOOKSHOT_EXISTS=true
[ -f "$REPO_ROOT/.claude/doc-coverage.json" ] && HOOKSHOT_EXISTS=true
S6 is always applicable but the score message differs — see Signal 6 below.
2. Determine Scope
PR-triggered mode: Given a PR number, identify which files changed:
# Get changed files from PR
GH_TOKEN=$GH_TOKEN gh api repos/$FULL_REPO/pulls/{PR_NUMBER}/files \
--jq '.[].filename'
Map each changed file to its domain using directory prefixes. Only grade domains with changes.
Full sweep mode: Grade all domains. Read domain list from ARCHITECTURE.md or infer.
3. Per-Domain Grading
For each domain in scope:
Signal 1: Doc Coverage
# Is this domain mentioned in docs/code-structure.md?
grep -i "{domain_name}" $REPO_ROOT/docs/code-structure.md 2>/dev/null && echo "COVERED" || echo "MISSING"
Score: ✅ covered / ❌ missing
Signal 2: FlowChad Coverage
Skip entirely if HAS_FRONTEND=false. Record as "N/A — no frontend detected" in applicability table.
# Only run if HAS_FRONTEND=true
if [ "$HAS_FRONTEND" = "true" ]; then
ls $REPO_ROOT/.flowchad/flows/ 2>/dev/null | grep -i "{domain_slug}" && echo "COVERED" || echo "MISSING"
fi
Score (frontend only): ✅ has flow / ❌ no flow
Signal 3: Staleness Delta
Find the most recent code commit date for files in this domain:
# Last commit touching domain files
git -C $REPO_ROOT log -1 --format="%ci" -- "{domain_directory_glob}" 2>/dev/null
Find the last update date for the domain's doc section:
# Last commit touching docs/code-structure.md
git -C $REPO_ROOT log -1 --format="%ci" -- docs/code-structure.md 2>/dev/null
Delta = days between last code commit and last doc update. Score: ✅ delta ≤30 days / ⚠️ delta 31-60 days (yellow) / ❌ delta >60 days
Signal 4: Open Issues
# Open issues tagged to this domain (use domain name as label or search term)
GH_TOKEN=$GH_TOKEN gh issue list --repo $FULL_REPO \
--state open --search "{domain_name}" \
--json number,title | jq length 2>/dev/null || echo "0"
Score: ✅ 0-3 open / ⚠️ 4-6 open (yellow) / ❌ >6 open
Signal 5: Test Coverage
# Look for coverage reports
ls $REPO_ROOT/coverage/ $REPO_ROOT/.nyc_output/ $REPO_ROOT/tmp/coverage/ 2>/dev/null
cat $REPO_ROOT/coverage/index.html 2>/dev/null | grep -o '[0-9.]*%' | head -1
# Rails: simplecov
cat $REPO_ROOT/coverage/.last_run.json 2>/dev/null | jq '.result.covered_percent'
If no coverage report is available → skip this signal (treat as neutral, not ❌). Score: ✅ ≥80% / ⚠️ 60-79% / ❌ <60% (only when coverage data is available)
Signal 6: Hookshot Coverage Staleness
COVERAGE_DATE=$(git -C $REPO_ROOT log -1 --format="%ci" -- .claude/doc-coverage.json 2>/dev/null)
DOCS_DATE=$(git -C $REPO_ROOT log -1 --format="%ci" -- docs/code-structure.md 2>/dev/null)
Distinguish two cases:
-
Hookshot not configured —
.claude/doc-coverage.jsonhas never existed (no git history for it, file absent): Score: ❌ "Hookshot not configured — recommend setup" -
Hookshot stale — file has existed (git history found) but docs were updated more recently: Score: ⚠️ "Hookshot stale (coverage {COVERAGE_DAY} < docs {DOCS_DAY})" — commit dates, not a day count
-
Hookshot current — coverage was updated after or same day as docs: Score: ✅ "Hookshot current"
Detection logic:
if [ -z "$COVERAGE_DATE" ] && [ ! -f "$REPO_ROOT/.claude/doc-coverage.json" ]; then
# Never been set up
S6_SCORE="❌"
S6_NOTE="Hookshot not configured — recommend setup"
elif [ -n "$DOCS_DATE" ] && [ -n "$COVERAGE_DATE" ]; then
# Both exist — compare dates
DOCS_EPOCH=$(date -d "$DOCS_DATE" +%s 2>/dev/null || date -j -f "%Y-%m-%d %H:%M:%S %z" "$DOCS_DATE" +%s 2>/dev/null)
COV_EPOCH=$(date -d "$COVERAGE_DATE" +%s 2>/dev/null || date -j -f "%Y-%m-%d %H:%M:%S %z" "$COVERAGE_DATE" +%s 2>/dev/null)
STALE_DAYS=$(( (DOCS_EPOCH - COV_EPOCH) / 86400 ))
if [ "$STALE_DAYS" -gt 0 ]; then
S6_SCORE="⚠️"
S6_NOTE="Hookshot stale (coverage ${COVERAGE_DATE%% *} < docs ${DOCS_DATE%% *})"
else
S6_SCORE="✅"
S6_NOTE="Hookshot current"
fi
else
S6_SCORE="❌"
S6_NOTE="Hookshot not configured — recommend setup"
fi
Compute Grade
Collect only applicable signals. Count failing signals (❌) among applicable signals only:
APPLICABLE_SIGNALS = all signals minus inapplicable ones
FAILING = count of ❌ in APPLICABLE_SIGNALS
YELLOW = count of ⚠️ in APPLICABLE_SIGNALS
SCORE = FAILING + (YELLOW * 0.5), rounded up
- SCORE = 0 → A
- SCORE = 1 → B
- SCORE = 2 → C
- SCORE ≥ 3 → D
- No docs at all → F
Example: repo with no frontend (S2 skipped), 5 applicable signals all green → grade A, not B.
4. Update QUALITY_SCORE.md
Read the existing file. Update each graded domain's row. Add new domains if discovered. Preserve existing rows for domains not in scope (only update what was re-scanned).
## Domains
| Domain | Grade | Last audit | Notes |
|--------|-------|------------|-------|
| {domain} | {grade} | {TODAY} | {brief note on what's missing, or "All signals green"} |
Write the updated file, then append to the History section:
| {TODAY} | {trigger: PR #{N} / weekly sweep / manual} | {N} domains scanned, {N} regressions, {N} improvements |
4a. Commit the write-back directly to the integration branch — no branch, no PR
Owner decision (2026-10-07): the write-back is committed straight to the scanned repo's
integration branch with [skip ci]; it never opens a branch or a PR. Sibling write-back PRs all
edited QUALITY_SCORE.md, conflicted on every merge and looped the full review chain.
- Branch: the repo's default branch, resolved at run time (
developforfellowship-dev/pylot, whose releases promotedevelop→main). Never hardcode it. - Mechanism: the GitHub Contents API through
scripts/contents-writeback.sh, notgit push. Pylot workers'git-push-guard.shdenies pushes tomain/master/develop(a path-scoped allow is fellowship-dev/pylot#3555, not shipped); do not retry a rejected push or look for another workaround. - Scope:
QUALITY_SCORE.mdonly. The helper refuses any other path and any message without[skip ci](exit 2) — fail the run loudly; never write another file this way.
- Nothing changed → report only. If no grade changed, no domain was added and no new Tooling drift was found, the only edit would be a History row. Discard it, commit nothing, post the step 8/9 report and finish.
- Otherwise commit. Fetch the branch's current file, apply this run's edits to it, put it:
WB="${PYLOT_WORKSPACE:-$HOME/.claude}/skills/entropy-check/scripts/contents-writeback.sh"
BASE=$(GH_TOKEN=$GH_TOKEN gh repo view "$FULL_REPO" --json defaultBranchRef --jq .defaultBranchRef.name)
MSG="chore: entropy scan — PR #{N} {title} [skip ci]" # weekly/manual: chore: entropy scan — weekly sweep $TODAY [skip ci]
FRESH=$(mktemp)
SHA=$(GH_TOKEN=$GH_TOKEN bash "$WB" fetch "$FULL_REPO" "$BASE" "$FRESH")
Re-apply this run's row updates, new domains, Tooling section and History row to $FRESH
(the branch's current content), keeping every other line exactly as it is there. Then:
GH_TOKEN=$GH_TOKEN bash "$WB" put "$FULL_REPO" "$BASE" QUALITY_SCORE.md "$FRESH" "$SHA" "$MSG"; echo "rc=$?"
rc=0 prints the commit sha. rc=3 means the sha went stale (HTTP 409/422 — another
write-back landed first): fetch again and re-apply, at most 3 attempts in total. Any other
code, or a third rc=3, fails the run loudly.
- Always edit the freshly fetched content; never upload a stale local copy over it.
- The commit message keeps the literal
[skip ci]tag so the commit triggers no CI or deploy. - A direct commit opens no PR, so it cannot re-trigger the post-merge entropy rule.
- The run is done once the commit lands; record its commit URL for step 8.
5. Signal Applicability Section
Include a "Signal Applicability" table in every report output:
## Signal Applicability
| Signal | Applicable? | Reason |
|--------|------------|--------|
| S1 Doc Coverage | Yes | — |
| S2 FlowChad | No | No frontend framework detected (bash/python scripts only) |
| S3 Staleness | Yes | — |
| S4 Open Issues | Yes | — |
| S5 Tests | Yes | No test framework found — recommend adding bats for shell scripts |
| S6 Hookshot | Yes | — |
Populate the Reason column with specifics:
- S2 not applicable: "No frontend framework detected" + what was found (e.g., "bash/python scripts only", "Go/Rails repo")
- S2 applicable: list detected framework (e.g., "Next.js detected in package.json")
- S5 no data: "No coverage report found — signal skipped"
- S5 data found: leave Reason blank or note the coverage percentage
- S6: always applicable; Reason shows the hookshot status detail
6. Staleness Report
For any domain graded C, D, or F — or where grade regressed from previous — output a finding:
## Entropy Findings — {TODAY}
### Regressions (grade dropped)
- {Domain}: {old grade} → {new grade}
Missing: {list of failing signals}
Last doc update: {date}
Last code commit: {date}
### Stable issues (same low grade)
- {Domain}: {grade} (unchanged since {date})
Missing: {list}
### Improvements (grade improved)
- {Domain}: {old grade} → {new grade}
### Clean (A or B)
- {Domain}: {grade}
7. Imported Lib Drift (Architecture Check)
This check moved here from maintenance. It is an architecture signal, not an infra check.
Retired: the imported-command drift check covered a workflow that is no longer used.
Skip this step; there is no ## Tooling drift to report.
8. PR-Triggered Output
When triggered by a PR merge event, output a comment-ready summary and post it on the merged PR once step 4a is done (write-back committed, or report-only):
## Entropy Scan — PR #{N} merged
Domains affected: {list}
Write-back: {commit URL on the default branch, or "none — no QUALITY_SCORE.md change"}
| Domain | Grade | Change | Notes |
|--------|-------|--------|-------|
| {domain} | {grade} | {→ or unchanged or ↑ or ↓} | {note} |
{If any regressions:}
⚠️ Doc staleness detected in: {domain list}
Recommended: update docs/code-structure.md for these domains before the next PR in this area.
Include the Signal Applicability table (see step 5) at the end of the comment.
9. Full Sweep Output (weekly cron)
## Entropy Weekly Sweep — {DATE}
{N} domains across {REPO_NAME}
### Grades
{Full grade table}
### Signal Applicability
{Signal applicability table}
### Action Items
{Domains graded D or F → recorded via file-finding.sh (existing issue or weekly digest)}
For D/F domains, record the finding through the shared filing helper (pylot-cli →
scripts/file-finding.sh). Stale docs are non-blocking, so the helper comments on an open
issue for the same domain or appends to the weekly digest issue — it never opens a new one:
FF="${PYLOT_WORKSPACE:-$HOME/.claude}/skills/pylot-cli/scripts/file-finding.sh"
GH_TOKEN=$GH_TOKEN bash "$FF" --repo "$FULL_REPO" \
--title "Entropy: {domain} docs critically stale (grade {grade})" \
--search "\"{domain} docs critically stale\"" \
--body "Domain **{domain}** scored **{grade}** in the weekly entropy scan.
**Missing signals:**
{list}
**Last code commit to this domain:** {date}
**Last doc update:** {date}
Fix: update \`docs/code-structure.md\` and run \`/hookshot\` to regenerate hooks."
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/fellowship-dev/dogfooded-skills/entropy-check">View entropy-check on skillZs</a>