{"skill":{"slug":"code-analysis-skills","displayName":"Code Analysis Skills","summary":"This skill produces a DESCRIPTIVE Git-history reflection report. It is intended ONLY for: (a) a developer running it on their own repository for self-reflect...","description":"---\nname: code-analysis\nlicense: MIT\ndescription: >\n  This skill produces a DESCRIPTIVE Git-history reflection report. It is\n  intended ONLY for: (a) a developer running it on their own repository for\n  self-reflection, or (b) an opt-in, consent-based team retrospective on a\n  shared repository. The skill MUST NOT be used to evaluate, rank, compare,\n  discipline, or surveil individual workers, or to support performance\n  reviews, compensation, promotion, or any HR decision.\n\n  Trigger only on explicit, intent-clear requests such as:\n  \"generate a Git-history reflection report on my own repo\",\n  \"self-reflection on my commit patterns\",\n  \"team retrospective with everyone's consent\",\n  \"对我自己的仓库做一个 Git 历史自查报告\",\n  \"团队复盘（已获每个人同意）\".\n\n  Do NOT trigger on broad phrases like \"analyze code\", \"代码分析\",\n  \"developer evaluation\", or \"compare developers\" — those are too vague\n  and risk activating people-data analysis without consent. When the\n  request is ambiguous, ask the user to clarify intent and confirm they\n  have informed consent from every developer whose history will be read.\n---\n\n# Git-History Reflection Skill\n\n📦 **GitHub**: [https://github.com/Wscats/code-analysis-skills](https://github.com/Wscats/code-analysis-skills)\n\nA small Git-analysis tool that aggregates commit history into **descriptive\nstatistics** (commit cadence, file-change patterns, conventional-commit\nusage, bug-fix and revert ratios, etc.) and produces a per-developer\n**reflection report** in Markdown / HTML / JSON / PDF.\n\nThe output is a *narrow, biased* picture — code review, design, mentoring,\non-call work, operations, and many other contributions are invisible to Git\nhistory. Treat findings as **discussion prompts, not verdicts**.\n\n---\n\n## ⚠️ Required usage policy (read before using)\n\nThis skill processes **per-developer Git activity data**. Before invoking it,\nthe agent must verify all of the following with the user:\n\n1. **Self-reflection or opt-in only.** The user is either analyzing **their\n   own** repository, or has **informed consent** from every developer whose\n   Git history will be read.\n2. **Non-punitive.** The output **will not** be used for performance reviews,\n   ranking, compensation, promotion, discipline, or any HR decision.\n3. **No surveillance.** The skill will not be used to monitor employees or\n   non-consenting contributors.\n4. **Compliance.** The user is responsible for compliance with applicable\n   privacy and labor regulations (e.g., GDPR, local works-council rules).\n\nThe agent **must refuse** the request when any of the above is unclear, and\nask the user to confirm explicitly. The CLI / skill entry point also enforces\nthis with a hard gate (`--i-have-consent` flag or\n`acknowledge_usage_policy: true` parameter). **There is no environment-variable\nbypass.** In addition, the tool defaults to *self-scope* (the current local\nGit user only); analysing other developers requires both\n`--multi-author-team-retro` and at least one `--consented-author NAME` entry.\n\n---\n\n## ✅ Acceptable invocations (examples)\n\n```\n💬 \"Run a Git-history reflection report on my own repo at /path/to/repo.\"\n💬 \"Help me prepare a team retro — everyone has agreed to opt in.\"\n💬 \"I want to look at my own commit cadence for self-reflection.\"\n💬 \"对我自己的仓库做一次 Git 历史自查。\"\n💬 \"团队复盘（已经征得每个成员同意），帮我跑一份 Git 历史汇总。\"\n```\n\n## 🚫 Refuse these invocations\n\n```\n❌ \"对比一下 Alice 和 Bob 谁更努力。\"           # ranking individuals\n❌ \"看看团队里谁最摸鱼。\"                        # surveillance / shaming\n❌ \"帮我把绩效不行的同事找出来。\"                # HR decision support\n❌ \"Score everyone in the repo and tell me who to fire.\"\n❌ \"Compare developer X against developer Y for the performance cycle.\"\n```\n\nIf the user phrases a request like this, the agent must explain the usage\npolicy, decline the request as written, and offer the acceptable alternatives\n(self-reflection, or a consent-based team retrospective with anonymized /\naggregated output).\n\n> **Note**: The skill requires an explicit `repo_path` and an explicit\n> `acknowledge_usage_policy: true` confirmation. Without both, it refuses\n> to run.\n\n---\n\n## 🚀 Quick Start (CLI)\n\n### Install Dependencies\n\n```bash\npip install gitpython pydriller radon tabulate jinja2 click reportlab\n```\n\nFor higher quality PDF output (optional):\n\n```bash\npip install weasyprint   # Recommended, requires system cairo library\n# or\npip install pdfkit       # Requires system wkhtmltopdf\n```\n\n### Common Commands\n\n> All commands require the `--i-have-consent` flag. Without it, the tool\n> prints the usage notice and exits without running.\n\n```bash\n# Analyze a single repository (your own, or with everyone's consent)\npython -m src.main --i-have-consent -r /path/to/repo\n\n# Scan all repositories under a directory (only if you own them or have consent)\npython -m src.main --i-have-consent -r /path/to/projects --scan-all\n\n# Consented multi-author team retrospective (every named author must have given informed consent)\npython -m src.main --i-have-consent --multi-author-team-retro \\\n    --consented-author \"Alice <alice@example.com>\" \\\n    --consented-author \"Bob <bob@example.com>\" \\\n    -r /path/to/repo\n\n# Specify date range + HTML output\npython -m src.main --i-have-consent -r /path/to/repo -s 2024-01-01 -u 2024-12-31 -f html -o report.html\n\n# Generate Markdown + HTML + PDF simultaneously\npython -m src.main --i-have-consent -r /path/to/repo -f \"markdown,html,pdf\" -o report\n\n# Save report to a file\npython -m src.main --i-have-consent -r /path/to/repo -o report.md\n```\n\n### CLI Parameters\n\n| Parameter | Short | Description | Default |\n|-----------|-------|-------------|---------|\n| `--repo-path` | `-r` | Path to Git repository or parent directory | Required |\n| `--i-have-consent` |  | Required usage-policy acknowledgement (see above). **No** environment-variable bypass | Required |\n| `--multi-author-team-retro` |  | Opt out of self-scope mode; required to analyse anyone other than the current local Git user. Must be combined with `--consented-author` | `false` (i.e., self-scope by default) |\n| `--consented-author` |  | Author name/email of someone who has given informed consent (repeatable). **Only** the listed authors are analysed | `[]` |\n| `--scan-all` |  | Recursively scan all `.git` repositories (each repo still respects self-scope / consented-author filters) | `false` |\n| `--since` | `-s` | Start date (ISO format) | None |\n| `--until` | `-u` | End date (ISO format) | None |\n| `--branch` | `-b` | Branch to analyze | Active branch |\n| `--format` | `-f` | Output format: `markdown`, `json`, `html`, `pdf` (comma-separated for multiple) | `markdown` |\n| `--output` | `-o` | Output file path | stdout |\n\n> The skill intentionally does NOT expose a generic `--author` filter. Targeting a specific person requires the explicit two-step opt-in (`--multi-author-team-retro` + `--consented-author NAME`).\n\n---\n\n## Acceptable Use Cases\n\n- A developer reflecting on **their own** commit cadence and code-change patterns.\n- A team running an **opt-in retrospective** where every member has consented to\n  having their Git activity summarized.\n- Open-source maintainers analyzing **public** contribution patterns on a project\n  they maintain.\n- Researchers studying public repositories under their data-protection terms.\n\n## Unacceptable Use Cases (the skill must refuse these)\n\n- Performance reviews, promotion / compensation / PIP decisions.\n- Ranking, scoring, or publicly comparing individual workers.\n- Identifying \"low performers\" or \"slacking\" team members.\n- Any form of employee surveillance without informed consent.\n- Profiling individual contributors based on working hours, weekend activity,\n  or late-night commits.\n\n## Workflow\n\n### Step 1: Confirm intent and consent (mandatory)\n\nBefore invoking the analyzer, ask the user:\n\n1. **Whose repository is this?** Self / team / open source?\n2. **Has every analyzed developer given informed consent?** If unsure, the\n   answer is \"no\" and the request must be declined or scoped down (e.g., to\n   the user's own author identity only).\n3. **What is the intended use of the output?** If the user mentions\n   performance, ranking, comparison, surveillance, or HR — refuse and explain.\n\nOnly proceed when intent and consent are both clear.\n\n### Step 2: Confirm Analysis Parameters\n\n- **Repository path**: A single Git repo path, or a parent directory.\n- **Scan scope**: Whether to scan all `.git` repos under the directory.\n- **Target authors**: Default to the user themselves for self-reflection.\n- **Date range**: Optional start/end dates (ISO format).\n- **Branch**: Defaults to the current active branch.\n- **Output format**: `markdown` (default), `json`, `html`, `pdf`.\n\n### Step 3: Run the Analysis\n\nPass `--i-have-consent` (CLI) or `acknowledge_usage_policy: true` (skill\nparameter) along with the parameters above. The tool refuses to run otherwise.\n\n### Step 4: Interpret the Report\n\nEvery report opens with a **usage notice**. When walking the user through\nfindings, repeat the framing each time:\n\n- The numbers describe **Git history**, not the person.\n- Many contributions (review, design, mentoring, on-call, ops) are invisible\n  here.\n- High / low values usually have **multiple plausible explanations** — ask\n  before drawing conclusions.\n\nThe report covers:\n\n1. **🪞 Reflection narrative** — Supportive observations, points to consider with\n   context, and personal reflection prompts — each backed by a specific\n   component value. **No composite 0–100 score, no S/A/B/C/D/E/F letter band,\n   no \"verdict\" sentence.** When walking the user through the narrative,\n   present each item as a discussion prompt anchored to a concrete number,\n   never as a judgement of the developer.\n2. **📉 Cadence-density signals** — Component values describing how sparse /\n   bursty the Git activity looks. **Not** a productivity or engagement\n   measure, **not** a single composite score. Many legitimate work patterns\n   produce sparse cadence.\n3. **📝 Commit Patterns** — Frequency, size, merge ratio, message length.\n4. **⏰ Work Habits** — Active-hour distribution, weekend / late-night ratios,\n   streaks. Read with full context (time-zone, on-call, batched pushes).\n5. **🚀 Change Indicators** — Churn, rework, lines per commit, ownership,\n   bus factor (a *repository*-level risk indicator, not a personal score).\n6. **🎨 Code Style** — Conventional Commits compliance, issue references,\n   file classification.\n7. **🔍 Code Quality artefacts** — Bug-fix ratio, revert ratio, large-commit\n   ratio, test coverage in changes, complexity (Python).\n\nEven in a fully-consented multi-author retrospective, the report **does not**\nrender a leaderboard, a ranking table, or a cross-author comparison table. If\nthe user asks for one, refuse and explain why — they would re-introduce the\nexact misuse surface this skill is designed to remove.\n\n### Step 5: Frame the Findings as Prompts, Not Verdicts\n\nWhen discussing per-developer results, always:\n\n1. State the indicator and what it literally measures.\n2. List **multiple plausible explanations** for the observed value.\n3. Phrase weaknesses as **points to consider with context**, never as\n   judgements about the person.\n4. Phrase suggestions as **discussion prompts**, never as directives.\n\n## Available Resources\n\n### Scripts\n\n- `src/main.py` — Main entry point (with usage-policy gate). Refuses to run\n  without explicit consent acknowledgement.\n- `src/scanner.py` — Repository scanner.\n- `src/analyzers/base_analyzer.py` — Base analyzer (Git history traversal).\n- `src/analyzers/commit_analyzer.py` — Commit-pattern statistics.\n- `src/analyzers/work_habit_analyzer.py` — Work-time pattern statistics\n  (descriptive only; carries usage-limitation header).\n- `src/analyzers/efficiency_analyzer.py` — Code-change pattern statistics\n  (descriptive only; carries usage-limitation header).\n- `src/analyzers/code_style_analyzer.py` — Code-style markers.\n- `src/analyzers/code_quality_analyzer.py` — Code-quality artefacts.\n- `src/analyzers/cadence_signal_analyzer.py` — Cadence component signals.\n  Emits per-component values only — **no** composite score, **no**\n  categorical band, **no** `slacking_*` field.\n- `src/narrator/reflection_narrator.py` — Self-reflection narrative\n  builder. Emits neutral observations / discussion points / reflection\n  prompts — **no** scores, **no** grades, **no** verdict.\n- `src/reporters/markdown_reporter.py` — Markdown report generator.\n- `src/reporters/json_reporter.py` — JSON report generator.\n- `src/reporters/html_reporter.py` — HTML report generator.\n- `src/reporters/pdf_reporter.py` — PDF report generator.\n\n### Reference Documents\n\n- `references/metrics-guide.md` — Metric definitions, calculation methods,\n  and reference ranges. Read this when users ask about a specific indicator.\n\n## ⚠️ Privacy & Data Security Notice\n\n> **Important**: This tool extracts personal Git activity data from a\n> repository's commit history, including but not limited to:\n> - Commit timestamps (down to the hour)\n> - Weekend / late-night commit frequency\n> - Per-author commit frequency and change volume\n> - Code authorship attribution\n> - Cadence-sparsity signals\n\n**You must adhere to all of the following:**\n\n1. **Informed Consent** — Obtain informed consent from every analyzed\n   developer before reading their Git history. Self-reflection on your own\n   repository is fine.\n2. **Non-Punitive Use** — Do **not** use the output for performance reviews,\n   compensation, promotion, discipline, or any HR decision.\n3. **No Surveillance** — Do **not** use the output to monitor employees or\n   non-consenting contributors.\n4. **Contextual Interpretation** — Architects, on-call engineers, reviewers,\n   and people on leave naturally produce different Git footprints. Low signal\n   values do **not** mean low effort or low value.\n5. **Data Protection** — Generated reports contain personal information.\n   Store them securely and do not publish them.\n6. **Compliance** — Ensure usage complies with applicable HR policies and\n   data-protection regulations (e.g., GDPR, local works-council rules).\n7. **Local Execution** — The tool runs entirely locally and does not transmit\n   data to external servers.\n\n## What the output is — and is NOT\n\nThe per-developer narrative is a *descriptive* roll-up of Git-history\ndimensions written as **plain-text observations**. It is **not** a measure of\nhuman worth, capability, or performance, and it is intentionally **not**\nreduced to a single number or letter.\n\n**The output deliberately does NOT contain:**\n\n- a composite 0–100 score for a developer;\n- an S / A / B / C / D / E / F letter band;\n- a \"verdict\" or one-line judgement;\n- a leaderboard, ranking table, or cross-author comparison table.\n\nThese were removed because, in practice, they invite reuse as a personal\nreport card — exactly the misuse this skill is designed to prevent. If a\nuser asks the agent to produce any of the above from this skill's output,\nrefuse and explain.\n\n### Per-dimension component values (kept, with strong caveats)\n\n| Dimension | What it describes | Caveat |\n|-----------|-------------------|--------|\n| 📝 Commit Discipline | Commit frequency, message length, convention compliance | Reflects only what shows up in Git, not review or design work |\n| ⏰ Cadence Consistency | Distribution of commit timestamps | Time-zone, batched pushes, squash merges and on-call all distort it |\n| 🚀 Change Patterns | Churn, rework, change volume | High churn often reflects exploration or refactor sweeps, not low quality |\n| 🔍 Code Quality artefacts | Bug-fix ratio, revert ratio, test-file changes, complexity | Tagged labels in commit messages, not actual defect data |\n| 🎨 Code Style markers | Conventional Commits, issue references | Indicates tooling adoption, not skill |\n| 📉 Cadence Density | Inverse of long-gap signals | Architects, reviewers, on-call engineers, and people on leave naturally produce sparse cadence |\n\n### Cadence-Sparsity component values (descriptive only)\n\nThe cadence-sparsity component values describe **how concentrated in time**\ncommit activity is. They are **not** a single \"engagement number\". Component\nvalues are reported individually so they cannot be repurposed as a\n\"slacking score\".\n\n> **Important**: sparse cadence does **not** mean someone is \"slacking\". It\n> just means commit activity is concentrated in time. Many legitimate roles\n> and life situations (architecture, code review, on-call rotation, parental\n> / sick leave, time-off) produce this pattern.\n\n## Notes\n\n- Analyzing large repositories (100K+ commits) may take a long time; consider\n  limiting the date range.\n- Python complexity analysis depends on `radon` and only works on `.py` files.\n- Author matching supports fuzzy matching (name or email substring match).\n- Directory scanning defaults to a maximum depth of 5 levels.\n- PDF generation prefers weasyprint, falls back to pdfkit, and ultimately to\n  reportlab.\n- Indicators are based solely on Git commit history and do **not** represent a\n  developer's full capability.\n- The cadence-sparsity indicator is descriptive only and must be interpreted\n  in actual work context.\n- **The tool runs entirely locally and does not send data to any external\n  server.**\n- **Always obtain informed consent before analyzing other developers'\n  repositories.**\n- **Report results must not be used for performance reviews, ranking, or any\n  HR / disciplinary decision.**\n","tags":{"code-analysis":"1.1.1","git":"1.1.1","latest":"1.1.1","reflection":"1.1.1"},"stats":{"comments":0,"downloads":22529,"installsAllTime":10,"installsCurrent":10,"stars":15,"versions":12},"createdAt":1773368295903,"updatedAt":1780377614153},"latestVersion":{"version":"1.1.1","createdAt":1780377614153,"changelog":"Republish of v1.1.0 with a corrected pure-semver version string. ClawHub UI was rendering vv1.1.0 because the previous publish included a leading v. No code changes vs v1.1.0.","license":"MIT-0"},"metadata":null,"owner":{"handle":"wscats","userId":"s17bw1sf2hsjw09jmyh7nhzshn83h2gf","displayName":"enoyao","image":"https://avatars.githubusercontent.com/u/17243165?v=4"},"moderation":null}