dev-playbooks 1.0.0

package/skills/devbooks-entropy-monitor/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: devbooks-entropy-monitor
+description: devbooks-entropy-monitor: Periodically collect system entropy metrics (structural entropy/change entropy/test entropy/dependency entropy), generate quantitative reports, and recommend refactoring when thresholds are exceeded. Use when user mentions "entropy measurement/complexity trends/refactoring warnings/code health/technical debt measurement".
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks: System Entropy Measurement and Alerts (Entropy Monitor)
+
+> Source: "The Mythical Man-Month" Chapter 16 "No Silver Bullet" — "The complexity of software entities is an essential property... controlling complexity is the key to software development"
+
+## Prerequisites: Configuration Discovery (Protocol-Agnostic)
+
+- `<truth-root>`: Current truth directory root
+- `<change-root>`: Change package directory root
+
+Before execution, **must** search for configuration in the following order (stop when found):
+1. `.devbooks/config.yaml` (if exists) → Parse and use its mappings
+2. `dev-playbooks/project.md` (if exists) → DevBooks 2.0 protocol, use default mappings
+4. `project.md` (if exists) → Template protocol, use default mappings
+5. If still unable to determine → **Stop and ask the user**
+
+**Key Constraints**:
+- If `agents_doc` (rules document) is specified in configuration, **must read that document first** before executing any operations
+- Do not guess directory roots
+- Do not skip reading the rules document
+
+## Core Philosophy
+
+**System Entropy** = Growth trend of code complexity over time
+
+Goals of entropy measurement:
+1. **Quantification**: All metrics are numerical values/ratios, enabling comparison
+2. **Trend Visibility**: Historical data supports trend analysis
+3. **Threshold Alerts**: Proactively recommend refactoring when thresholds are exceeded
+4. **Periodic Execution**: Run as an independent task, not embedded in every code review
+
+## Execution Method
+
+1) First read and follow: `_shared/references/universal-gating-protocol.md` (verifiability + structural quality gating).
+2) Strictly output according to the complete prompt: `references/entropy-measurement-methodology.md`.
+
+## Scripts
+
+| Script | Purpose | Example |
+|--------|---------|---------|
+| `entropy-measure.sh` | Collect entropy metrics | `entropy-measure.sh --project-root /path/to/repo` |
+| `entropy-report.sh` | Generate report | `entropy-report.sh --output report.md` |
+
+## Metrics System (Four Dimensions)
+
+### A) Structural Entropy
+
+| Metric | Collection Method | Healthy Threshold | Description |
+|--------|------------------|-------------------|-------------|
+| Average Cyclomatic Complexity | Static analysis | < 10 | Function-level average |
+| Cyclomatic Complexity P95 | Static analysis | < 20 | 95th percentile |
+| File Lines P95 | Line count | < 500 | Oversized file warning |
+| Function Lines P95 | Static analysis | < 50 | Overly long function warning |
+
+### B) Change Entropy
+
+| Metric | Collection Method | Healthy Threshold | Description |
+|--------|------------------|-------------------|-------------|
+| Hotspot File Ratio | git log | < 0.1 | Ratio of frequently modified files |
+| Coupled Change Rate | git log | < 0.3 | Ratio of file pairs frequently modified together |
+| Code Churn Rate | git diff | < 0.5 | Ratio of new code deleted within 30 days |
+
+### C) Test Entropy
+
+| Metric | Collection Method | Healthy Threshold | Description |
+|--------|------------------|-------------------|-------------|
+| Flaky Test Ratio | CI logs | < 0.01 | Ratio of unstable tests |
+| Test Coverage | Coverage tools | > 0.7 | Code coverage rate |
+| Test/Code Ratio | Line count | > 0.5 | Ratio of test code to production code |
+
+### D) Dependency Entropy
+
+| Metric | Collection Method | Healthy Threshold | Description |
+|--------|------------------|-------------------|-------------|
+| Outdated Dependency Ratio | npm/pip audit | < 0.2 | Dependencies more than 2 major versions behind |
+| Security Vulnerability Count | Security scan | = 0 | Number of high-risk vulnerabilities |
+| Dependency Depth P95 | Dependency tree analysis | < 10 | Levels of transitive dependencies |
+
+## Output Locations
+
+| Output | Path | Description |
+|--------|------|-------------|
+| Entropy Report | `<truth-root>/_meta/entropy/entropy-report-YYYY-MM-DD.md` | Current collection report |
+| Historical Data | `<truth-root>/_meta/entropy/history.json` | All historical metrics |
+| Threshold Configuration | `<truth-root>/_meta/entropy/thresholds.json` | Configurable thresholds |
+
+## Recommended Execution Frequency
+
+| Project Size | Recommended Frequency | Trigger Method |
+|--------------|----------------------|----------------|
+| Small (< 10K LOC) | Weekly | Manual / CI scheduled |
+| Medium (10K-100K LOC) | Daily | CI scheduled |
+| Large (> 100K LOC) | Every merge | PR merge trigger |
+
+## Relationship with Other Skills
+
+| Skill | Relationship |
+|-------|--------------|
+| devbooks-code-review | Entropy measurement is **not** embedded in every review, runs as independent task |
+| devbooks-proposal-author | Entropy reports can serve as data support for refactoring proposals |
+| devbooks-impact-analysis | Changes in high-entropy areas require more careful impact analysis |
+
+## Hard Constraints
+
+1. **Quantification First**: All metrics must be numerical values/ratios, no subjective evaluations
+2. **Configurable Thresholds**: All thresholds managed through `thresholds.json`, not hardcoded
+3. **Historical Traceability**: Each collection result appended to `history.json`
+4. **Independent Execution**: Not embedded in other workflows, runs as periodic independent task
+
+---
+
+## Context Awareness
+
+This Skill automatically detects context before execution to select appropriate collection scope.
+
+Detection rules reference: `skills/_shared/context-detection-template.md`
+
+### Detection Flow
+
+1. Detect if historical data file exists
+2. Detect last collection time
+3. Detect if any metrics exceed thresholds
+
+### Modes Supported by This Skill
+
+| Mode | Trigger Condition | Behavior |
+|------|-------------------|----------|
+| **Initial Collection** | Historical data does not exist | Execute full collection and establish baseline |
+| **Incremental Collection** | Interval since last collection exceeded | Collect new data and compare trends |
+| **Alert Mode** | Metrics exceeding thresholds detected | Generate alert report and recommend refactoring |
+
+### Detection Output Example
+
+```
+Detection Results:
+- Historical data: Exists (15 records)
+- Last collection: 2026-01-10
+- Metrics exceeding thresholds: 2 (Cyclomatic Complexity P95, Hotspot File Ratio)
+- Execution mode: Incremental Collection + Alert Mode
+```
+
+---
+
+## MCP Enhancement
+
+This Skill supports MCP runtime enhancement, automatically detecting and enabling advanced features.
+
+MCP enhancement rules reference: `skills/_shared/mcp-enhancement-template.md`
+
+### Required MCP Services
+
+| Service | Purpose | Timeout |
+|---------|---------|---------|
+| `mcp__ckb__getHotspots` | Get hotspot file analysis | 2s |
+| `mcp__ckb__getStatus` | Detect CKB index availability | 2s |
+
+### Detection Flow
+
+1. Call `mcp__ckb__getStatus` (2s timeout)
+2. If CKB available → Use `getHotspots` for precise hotspot analysis
+3. If timeout or failure → Fall back to Git history statistics
+
+### Enhanced Mode vs Basic Mode
+
+| Feature | Enhanced Mode | Basic Mode |
+|---------|---------------|------------|
+| Hotspot Analysis | CKB real-time analysis (includes complexity) | Git log change frequency statistics |
+| Coupling Detection | Call graph analysis | File co-change analysis |
+| Trend Prediction | Based on complexity change rate | Based on change frequency |
+
+### Fallback Notice
+
+When MCP is unavailable, output the following notice:
+
+```
+Warning: CKB unavailable, using Git history for entropy measurement.
+Hotspot analysis based on change frequency, does not include code complexity data.
+```
+

package/skills/devbooks-entropy-monitor/references/entropy-metrics-methodology.md

@@ -0,0 +1,218 @@
+# Entropy Metrics Methodology
+
+> Source: *The Mythical Man-Month*, Ch. 16 “No Silver Bullet” — “the complexity of software is an essential property… controlling complexity is key”
+
+Highest-priority instruction:
+- Before executing this prompt, read `_shared/references/universal-gating-protocol.md` and follow all protocols in it.
+
+You are the **Entropy Monitor**. Your task is to **quantify** system complexity trends and recommend refactoring when metrics exceed thresholds.
+
+## Core idea
+
+**Entropy** = a measure of system disorder.
+
+In software systems:
+- **Low entropy** = clear structure, controllable change, healthy tests, healthy dependencies
+- **High entropy** = messy structure, frequent hotspots, fragile tests, dependency decay
+
+Entropy growth is inevitable, but it can be reduced via **intentional refactoring**.
+
+## Four-dimension metrics framework
+
+### A) Structural entropy
+
+Measures static code complexity.
+
+| Metric | Collection | Healthy threshold | Signal |
+|-------|------------|------------------|--------|
+| Cyclomatic complexity mean | static analysis | < 10 | functions are too complex |
+| Cyclomatic complexity P95 | static analysis | < 20 | extreme outlier functions exist |
+| File LOC P95 | `wc -l` | < 500 | files too large; split |
+| Function LOC P95 | static analysis | < 50 | functions too long; extract |
+
+Suggested tools:
+- JavaScript/TypeScript: `eslint --rule complexity`
+- Python: `radon cc`
+- Go: `gocyclo`
+- Java: `PMD`, `Checkstyle`
+
+### B) Change entropy
+
+Measures dynamic change patterns.
+
+| Metric | Collection | Healthy threshold | Signal |
+|-------|------------|------------------|--------|
+| Hotspot ratio | git log analysis | < 0.1 | a few files absorb too much change |
+| Coupled-change ratio | git log analysis | < 0.3 | implicit coupling across files |
+| Churn ratio | git diff analysis | < 0.5 | newly added code is quickly removed |
+
+**Hotspot**: a file modified more than 5 times within the analysis window.
+
+**Coupled change**: two files modified together in the same commit frequently.
+
+### C) Test entropy
+
+Measures test quality and stability.
+
+| Metric | Collection | Healthy threshold | Signal |
+|-------|------------|------------------|--------|
+| Flaky ratio | CI log analysis | < 0.01 | unreliable tests |
+| Coverage | coverage tooling | > 0.7 | critical paths untested |
+| Test/code ratio | line counts | > 0.5 | insufficient test investment |
+
+**Flaky test**: for the same code, repeated runs yield inconsistent results.
+
+### D) Dependency entropy
+
+Measures dependency health.
+
+| Metric | Collection | Healthy threshold | Signal |
+|-------|------------|------------------|--------|
+| Outdated ratio | `npm outdated` / `pip-audit` | < 0.2 | tech debt accumulation |
+| Vulnerabilities | security scans | = 0 | security risk |
+| Dependency depth P95 | dependency tree analysis | < 10 | supply-chain complexity |
+
+**Outdated dependency**: lags the latest by more than 2 major versions.
+
+## Execution flow
+
+### 1) Collect metrics
+
+```bash
+entropy-measure.sh --project-root /path/to/repo --days 30
+
+# Output:
+<truth-root>/_meta/entropy/metrics-YYYY-MM-DD.json
+```
+
+### 2) Generate report
+
+```bash
+entropy-report.sh --output report.md
+
+# Output:
+<truth-root>/_meta/entropy/entropy-report-YYYY-MM-DD.md
+```
+
+### 3) Trend analysis
+
+Historical data lives at `<truth-root>/_meta/entropy/history.json` and can be used to:
+- plot trends
+- compute deltas period-over-period
+- estimate entropy growth rate
+
+### 4) Threshold alerts
+
+If any metric exceeds threshold:
+1. report shows 🔴 status
+2. an alert entry is generated
+3. a concrete action is recommended
+
+## Threshold configuration
+
+Thresholds live at `<truth-root>/_meta/entropy/thresholds.json`:
+
+```json
+{
+  "structural": {
+    "complexity_mean": 10,
+    "complexity_p95": 20,
+    "file_lines_p95": 500,
+    "function_lines_p95": 50
+  },
+  "change": {
+    "hotspot_ratio": 0.1,
+    "coupling_ratio": 0.3,
+    "churn_ratio": 0.5
+  },
+  "test": {
+    "flaky_ratio": 0.01,
+    "coverage_min": 0.7,
+    "test_code_ratio_min": 0.5
+  },
+  "dependency": {
+    "outdated_ratio": 0.2,
+    "vulnerabilities": 0
+  }
+}
+```
+
+Threshold tuning principles:
+- tune based on your project reality
+- tighten gradually; do not “one-shot” it
+- record rationale and date for changes
+
+## Connecting to refactoring proposals
+
+When multiple entropy metrics are out of bounds:
+
+1. Use `devbooks-proposal-author` to start a refactoring proposal
+2. Cite entropy report data in the “Why” section of `proposal.md`
+3. Set verifiable entropy-reduction targets
+
+Example:
+
+```markdown
+## Why
+
+Entropy report (2024-01-15) shows:
+- hotspot ratio 0.15 (threshold 0.1)
+- file LOC P95 = 800 (threshold 500)
+
+Recommendation: split `src/core/engine.ts` (1200 LOC) into multiple modules.
+
+## Validation
+
+After refactor:
+- hotspot ratio < 0.08
+- file LOC P95 < 400
+```
+
+## Recommended cadence
+
+| Project size | Cadence | Execution |
+|-------------|---------|-----------|
+| Small (< 10K LOC) | weekly | manual run |
+| Medium (10K–100K LOC) | daily | scheduled CI job |
+| Large (> 100K LOC) | per merge | trigger after PR merge |
+
+## CI integration example
+
+### GitHub Actions
+
+```yaml
+name: Entropy Monitor
+on:
+  schedule:
+    - cron: '0 2 * * *'  # 2am daily
+  workflow_dispatch:
+
+jobs:
+  measure:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full git history required
+      - name: Run entropy measurement
+        run: ./scripts/entropy-measure.sh
+      - name: Generate report
+        run: ./scripts/entropy-report.sh
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: entropy-report
+          path: specs/_meta/entropy/
+```
+
+## Hard constraints
+
+1. **Quantitative first**: all metrics must be numeric/ratios; no subjective “looks complex”
+2. **Thresholds are configurable**: managed via config files, not hard-coded
+3. **History is preserved**: append each run to history.json to enable trend analysis
+4. **Runs independently**: not embedded in every code review; run periodically as a standalone task
+5. **Action-oriented**: every threshold breach must have a concrete recommendation
+
+## References
+
+- *The Mythical Man-Month*, Ch. 16 “No Silver Bullet”