agentleFS
joris887joris887/exosuit/.claude/skills/weekly-maintenance/SKILL.md

weekly-maintenance

Skill9 starsChanged 3 months agoMITView on GitHub

Execute comprehensive weekly maintenance routine (1-2 hours, Friday recommended). Includes health checks, quality review, dependency governance, activity insights, and planning.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the project's quality/health tools (from CLAUDE.md Commands section):

    line 20
  2. Distinctive:

    Use the code-quality skill to analyze the entire codebase:

    line 36
  3. Distinctive:

    Check for pattern consistency violations

    line 40
  4. Distinctive:

    Check key documentation for accuracy:

    line 44
  5. Very specific:

    Metrics freshness: If docs/progress.md → ## Sprint History has ≥2 data rows but ## Metrics table still shows "—" values, sprint-end is not …

    line 50
  6. Distinctive:

    Check for outdated dependencies using the project's package manager:

    line 54
  7. Distinctive:

    Run dependency auditing tools:

    line 62
  8. Very specific:

    Read docs/reference/SECRETS_INVENTORY.md and check:

    line 93
  9. Very specific:

    If docs/reference/SECRETS_INVENTORY.md does not exist but the project uses environment variables or credentials, note this as a gap: "No …

    line 99
  10. Distinctive:

    Run the project's dependency audit tool (same as section 4, but focused on security):

    line 103
  11. Very specific:

    Read docs/technical-debt.md and perform the weekly debt review:

    line 118
  12. Distinctive:

    Check this week's commits and code quality findings for new debt.

    line 128
  13. Distinctive:

    Run the metrics script to assess rule effectiveness:

    line 147
  14. Distinctive:

    Check the health of project ground rules:

    line 174
  15. Distinctive:

    Update @docs/progress.md with:

    line 229

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

weekly-maintenance

Execute comprehensive weekly maintenance routine (1-2 hours, Friday recommended):

1. Codebase Health Check

Run the project's quality/health tools (from CLAUDE.md Commands section):

# Use project-specific commands, e.g.:
# just health, npm run lint, cargo clippy, etc.

Report on:

  • Complexity trends (should be stable or decreasing)
  • Duplication percentage (target: <5%)
  • High-churn files that may need attention
  • Dead code: unused exports, orphaned functions (run monthly or when codebase > 5K LOC)

2. Code Quality Agent Review

Use the code-quality skill to analyze the entire codebase:

  • Flag any functions with CCN >10
  • Identify duplication patterns
  • Check for pattern consistency violations

3. Documentation Review

Check key documentation for accuracy:

  • @CLAUDE.md accuracy (commands, paths, patterns still correct?)
  • @docs/progress.md completeness
  • Any drift between docs and implementation
  • Documentation efficiency: Key context files (CLAUDE.md, progress.md, BACKLOG_INDEX.md) are loaded every session — keep them lean. Archive stale content, deduplicate, condense verbose sections.
  • Metrics freshness: If docs/progress.md → ## Sprint History has ≥2 data rows but ## Metrics table still shows "—" values, sprint-end is not computing metrics — flag as a measurement gap. The feedback loop is broken: data collected but not surfaced.

4. Dependency Review

Check for outdated dependencies using the project's package manager:

# npm outdated, pip list --outdated, cargo outdated, etc.

Dependency Health Check

Run dependency auditing tools:

# npm audit / pip-audit / cargo audit / bundler-audit

Flag and report:

  • Recently added packages (added since last maintenance) — verify they exist in the registry and are well-established
  • Young packages (< 7 days old) — flag as supply chain risk
  • Known vulnerabilities — categorize by severity
  • Lockfile sync — verify lockfile matches dependency manifest
  • Recently deprecated packages — check for deprecation notices

Dependency Report

### Dependency Health
- Total dependencies: [count]
- Outdated: [count]
- Vulnerabilities: [critical/high/medium/low counts]
- Recently added: [list with age and download counts]
- Lockfile in sync: [yes/no]

4.3. Security Health Check

Perform a focused security health review:

Secrets Inventory Review

<IF condition="docs/reference/SECRETS_INVENTORY.md exists"> Read `docs/reference/SECRETS_INVENTORY.md` and check: - **Overdue rotations:** Scan the `Next Due` column for dates in the past. Flag by severity: ≤7 days (warning), 8-30 days (high priority), >30 days (critical — rotate immediately). - **Missing rotation methods:** Any secrets without a documented `Rotation Method` should be flagged. - **Critical secrets without automation:** Secrets classified as `critical` that rely on `manual` rotation are high-risk. </IF> <ELSE> If `docs/reference/SECRETS_INVENTORY.md` does not exist but the project uses environment variables or credentials, note this as a gap: "No secrets inventory — consider creating one from the template in the framework scaffold." </ELSE>

Dependency Security Audit

Run the project's dependency audit tool (same as section 4, but focused on security):

# npm audit --audit-level=high / pip-audit / cargo audit / govulncheck / bundler-audit

Report Critical and High vulnerabilities. These should be addressed before the next sprint.

Quarterly Full-Repo Secret Scan

On the first weekly-maintenance of each quarter, run a full repository secret scan if Gitleaks or similar is available:

gitleaks detect --source . --no-git --report-format json 2>/dev/null

Report any findings. This catches secrets missed by the per-file post-edit hook.

4.5. Technical Debt Register Review

Read docs/technical-debt.md and perform the weekly debt review:

Triage active items

For each active item:

  • Interest rate reassessment — check coupling to determine if interest is Growing or Stable. Run grep -rn on the debt item's Location files to count how many other files import/reference them. High fan-in (imported by >5 files) + active debt = Growing interest. Isolated files with no dependents = Stable or Shrinking.
  • Severity check — has the item worsened? (e.g., new incidents, more files affected). Promote if so.
  • Resolution progress — is there a linked story? If not and item is >30 days old, consider creating one.
  • Accept or resolve — can any items move to "Accepted" (conscious trade-off) or "Resolved" (fixed)?

Detect new debt

Check this week's commits and code quality findings for new debt. Specifically scan for the 5 AI-specific debt types:

  1. Comprehension debt — grep git log for AI-assisted commits (Co-Authored-By: Claude or similar). For files with high AI-commit ratio that haven't been manually modified since, flag as potential comprehension debt. The risk: code ships faster than developers understand it.
  2. Pattern violation debt — compare this week's changes against docs/reference/CODING_STANDARDS.md (if exists). AI introduces inconsistent patterns at 3x the human rate for formatting, 2x for naming.
  3. Duplication debt — check for near-duplicate code blocks introduced this week. AI regenerates rather than reusing existing functions.
  4. Phantom dependency debt — verify all imports added this week reference packages that exist in the project's dependency manifest (package.json, requirements.txt, go.mod, Cargo.toml, etc.).
  5. Verification debt — check if large AI-generated diffs have corresponding test coverage. Code reviewed without full understanding creates hidden risk.

Tag new items with origin: ai-generated when the source commit has AI co-author markers.

Housekeeping

  1. Review dates — update "Last reviewed" to today, "Next review" to +7 days
  2. Resolved cleanup — delete resolved items older than 90 days
  3. AI trends — at quarter boundaries, update the AI Debt Trends table with counts
  4. Active count — update header: Active items: X | Resolved this quarter: Y
  5. Sprint candidates — flag items with priority score ≥4.5 or interest "Growing" for next sprint planning. /sprint-start reads these during its debt health check.

5. Rule Health Review

Run the metrics script to assess rule effectiveness:

bash scripts/pm/metrics.sh

Review the "Rule Triggers" section. Flag:

  • Over-active rules (>20 triggers/week) — may be too broad or indicating a persistent issue
  • Silent rules (0 triggers in 30+ days) — may be too narrow or addressing a solved problem
  • High-failure skills (success rate <70%) — investigate common failure points

Record findings in the weekly summary below.

Also run the progress dashboard for trend signals and relative changes:

bash scripts/pm/metrics.sh --progress

Review the output for:

  • Any metrics with Δ3avg >50% (rapid change worth investigating)
  • Leading vs Lagging divergences (early warning signals)
  • Persistent 3-sprint trends that haven't been addressed

5.5. Ground Rules Health

<IF condition="docs/reference/GROUND_RULES.md exists and has GR-NNN rules"> Check the health of project ground rules:
  • Expired exceptions — scan the Exception Log table for rows where Expires date has passed. Flag for resolution (remove exception or renew with justification).
  • Stale rules — if Change History shows no updates in 6+ months, the rules may need a freshness review.
  • Compliance trends — read recent sprint specs (docs/sprints/sprint-N.md) → ## Outcome → Ground rules field. Consistent violations of one rule may mean the rule is unrealistic, or enforcement is missing.
  • Enforcement gaps — for rules with Enforced-by: auto:, verify the tool/test still exists and runs in CI. Unconfigured enforcement = paper rule.</IF>

5.7. Architecture Decision Health

<IF condition="docs/adr/ contains ADR files"> Review the health of architecture decision records:
  • Low-confidence ADRs — scan for confidence: low in frontmatter. For each, check whether Reconsider when conditions have been met by the current codebase state. Flag any that need re-evaluation.
  • Stale ADRs — if no ADR has been created or reviewed in 90+ days on an actively developed project, the team may be making undocumented decisions. Flag as a process gap.
  • Supersession chains — check for superseded-by chains longer than 2 (A→B→C). These indicate a volatile decision area that may need a ground rule instead.
  • Ground rule candidates — if 2+ accepted ADRs address the same concern, suggest promoting to docs/reference/GROUND_RULES.md.
  • ADR count health — projects with <5 ADRs and >10 major dependencies are likely under-documenting decisions.</IF>

5.9. Weekly Activity Insights

Parse docs/sessions/.activity-log.jsonl for the past 7 days of activity:

ACTIVITY_LOG="docs/sessions/.activity-log.jsonl"
WEEK_AGO=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d "7 days ago" +%Y-%m-%d 2>/dev/null)
if [ -f "$ACTIVITY_LOG" ] && [ -s "$ACTIVITY_LOG" ]; then
  # Filter to last 7 days and analyze
  # Top 3 most-edited files this week
  # Skill invocation counts
  # Test failure patterns (same test failing repeatedly = flaky or fundamental)
  # Edit-to-test ratio for the week
fi

Present as a concise summary (5-10 lines max):

### Weekly Activity Insights
- **Hot files:** `src/auth/login.ts` (23 edits), `src/api/users.ts` (15 edits), `tests/auth.test.ts` (12 edits)
- **Skills used:** /story-cycle (8x), /commit (6x), /debug-session (2x), /sprint-end (1x)
- **Test health:** 3 failures this week — `auth.test.ts:login_expired_token` failed 2x (possible flaky test)
- **Edit-to-test ratio:** 3.2 (good TDD discipline)
- **Sessions:** 4 sessions, avg 45 min each

Flag patterns worth investigating:

  • Same test failing in multiple sessions → likely flaky or fundamental issue
  • High edit-to-test ratio (>5.0) → TDD discipline slipping
  • One file getting >30% of all edits → possible hotspot needing refactoring
  • Skills with repeated failures → investigate common failure points

6. Weekly Summary

Update @docs/progress.md with:

## Week of [Date]

### Sprints Completed
- [Sprint X]: [Story ID] - [Title]

### Metrics Status
Reference `docs/progress.md` → `## Metrics` table for current sprint metrics.
Additional weekly indicators not tracked per-sprint:
- Complexity trend: [stable/increasing/decreasing]
- Duplication: X%
- Dependency health: [count] vulnerabilities, [count] outdated

### Technical Debt
- New items added: [count] (AI-origin: [count])
- Items resolved: [count]
- Active totals: [N] critical / [N] high / [N] medium / [N] low
- Growing-interest items needing attention: [list or "none"]

### Next Week Focus
- [Story IDs planned]

7. Plan Next Week

Review @docs/reference/BACKLOG_INDEX.md and relevant epic files to identify:

  • Next 3-5 stories to target
  • Any blockers to address first
  • Dependencies between stories

Output comprehensive weekly report with actionable items.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.