contributions-graph-filler-vp

name	contributions-graph-filler-vp
description	Explicit-only skill for planning and optionally applying retrospective maintenance commits across the user's own GitHub repositories. Use only when the user directly names `contributions-graph-filler-vp` or `$contributions-graph-filler-vp`. Do not trigger implicitly from generic mentions of GitHub, commits, contribution graphs, or green walls.

Github 绿墙刷漆计划

Use this skill only after the user explicitly invokes it by name.

The skill generates a reproducible retrospective maintenance plan across the user's own GitHub repositories. It must output an Excel review file first, then wait for explicit user approval before executing a push-and-cleanup-PR workflow.

Boundaries

• Do not create empty commits.
• Do not create fake placeholder code.
• Do not create temporary content intended to be deleted after commit.
• Do not operate on repositories that are not owned or maintained by the target account.
• Do not include forks by default.
• Do not push unless the user explicitly requests push after reviewing the plan.
• Do not mutate Git history during normal cleanup.
• Do not create standalone local-only commit batches.
• Do not execute push-and-cleanup-PR until the user reviews and explicitly approves the generated Excel plan.
• Do not open PRs, issues, releases, or comments except the per-repository cleanup PRs created by the approved workflow.
• Prefer durable artifacts: documentation, analysis notes, evaluation checklists, test plans, configuration notes, maintenance checklists.
• Do not use history rewriting as the normal workflow.

Required Inputs

Require these before generating a plan:

• GitHub account or organization, for example VectorPeak.
• Date range, for example 2026-03-01 -> 2026-04-01.
• Activity profile. Default: vibe_coding_builder.

If the user does not specify a profile, use vibe_coding_builder.

Preflight Checks

Before scanning repositories, verify the local GitHub environment:

• gh must be installed and available on PATH.
• gh auth status -h github.com must succeed.
• gh api rate_limit must succeed to confirm GitHub API connectivity.

If any check fails, stop before planning and tell the user the exact failed check and the likely fix, such as installing GitHub CLI, running gh auth login, or checking network/proxy access.

Repository Gate

Scan repositories for the target account before planning.

Eligible repositories must be:

• owned by the target account;
• not forks, unless the user explicitly allows forks;
• not archived;
• code or project repositories, including code-heavy documentation, skills, RAG, ML, app, tooling, or knowledge-base repos;
• writable by the user if execution mode is local commit or push.

Require more than 10 eligible repositories. If eligible repositories are <= 10, stop and ask the user to either create more real repositories, allow private repositories, allow documentation/knowledge repositories, or narrow the requested operation.

Do not create repositories unless the user explicitly asks for repository creation in a separate instruction.

Execution Modes

Default mode is plan-only.

• plan-only: generate a dated Excel review plan. Do not write repository files.
• push-and-cleanup-pr: after explicit approval of the Excel plan, create durable commits, push them to GitHub default branches, verify the remote contains the pushed commits, then create one cleanup PR per affected repository to delete generated docs.
• cleanup-pr: create cleanup PRs only from a pushed manifest. Do not create additional retrospective commits.

Do not offer local-commit as a final execution mode. A local commit may exist only as a transient step inside push-and-cleanup-pr, and it must be pushed before the operation is considered complete.

When unsure, stay in plan-only.

Mandatory Excel Approval

Always split execution into two turns:

1. Generate an Excel review file with daily totals and commit details.
2. Stop and ask the user to approve that exact file before any push-and-cleanup-pr.

The Excel review file must include:

• date;
• target commit count generated by the selected activity profile;
• existing author commit count already present on GitHub for that date;
• planned new commit count after subtraction;
• commit details with time, repository, message, and planned file path.

Never treat a TSV, console preview, or chat summary as sufficient approval for execution. The user must approve the Excel plan file explicitly.

Existing Commit Deduction

Before finalizing the plan, count existing GitHub commits for each planned active day.

Use the target account as the default author unless the user specifies another author:

author:<author> author-date:<YYYY-MM-DD>..<YYYY-MM-DD> user:<account>

For each date:

planned_new_commit_count = max(0, target_commit_count - existing_author_commit_count)

Example: if the profile generates 5 commits for 2026-03-25 and GitHub already has 2 matching author commits that day, generate only 3 new commit tasks.

Worktree Selection

Before push-and-cleanup-pr, map each planned repository to a local worktree.

• Prefer an existing local repository only when its remote URL matches the planned GitHub repository and git status --porcelain is clean.
• If the matching local repository is dirty, stop and ask the user whether to use an isolated clone or handle the dirty worktree first.
• If multiple local clones match the same repository, choose a clean canonical path only after showing the candidates to the user.
• Use an isolated clone when the user wants a test run, when existing worktrees are dirty, or when cleanup safety is more important than reusing local checkout state.
• Record the selected path and pre-session HEAD for every repository in the manifest before creating any commit.

Push-And-Cleanup-PR Mode

Push-and-cleanup-PR must be manifest-driven.

• Create commits only after Excel approval.
• Push every skill-created commit to the repository default branch.
• Verify that each pushed commit is reachable from the remote default branch before creating cleanup branches.
• Record repository path, branch, pre-session HEAD, pushed commit SHAs, remote verification status, cleanup branch, cleanup commit SHA, and cleanup PR URL in the manifest.
• For each affected repository, create a cleanup branch from the remote default branch and delete the generated docs recorded in the manifest.
• Open one draft cleanup PR per affected repository. GitHub PRs cannot span multiple repositories.
• Do not use git revert as the default cleanup path.
• Do not use git reset --hard plus force push in the normal workflow.
• Never delete unrelated user docs, unrelated commits, merge commits, or files not created by this skill unless the user explicitly asks to remove whole generated docs directories.
• Show a cleanup summary: repository, cleanup branch, deleted file count, cleanup commit SHA, PR URL, and whether all manifest-owned docs were removed from the PR branch.
• Stop on dirty working trees unless the user explicitly provides a safe stash/commit instruction.

Cleanup Directories

Generated docs directories commonly used by this skill are:

docs/notes/
docs/testing/
docs/config/
docs/maintenance/
docs/evaluation/
docs/editorial/
docs/experiments/
docs/review/

When the user asks to "delete the docs folders", remove the generated files under these directories in each affected repository and remove now-empty directories. Do not delete unrelated documentation outside the manifest scope.

Operational Lessons

Keep history rewriting as incident recovery knowledge, not as the default workflow.

If an older run used git revert and the user later asks to remove those revert commits from GitHub-visible history, do not revert the revert commits. That creates additional current-day commits. Instead, only after explicit confirmation for every affected repository:

1. Load the pushed manifest and withdrawal manifest.
2. Verify every affected repository, branch, pre_withdraw_head, post_withdraw_head, source commit SHA, and revert commit SHA.
3. Confirm all affected worktrees are clean.
4. For repositories whose remote default branch is exactly post_withdraw_head, reset the branch to pre_withdraw_head and push with --force-with-lease.
5. For repositories with legitimate later commits after post_withdraw_head, drop only the revert segment and replay or rebase the later commits onto pre_withdraw_head.
6. Verify no recorded revert SHA remains reachable from the remote default branch.
7. Return to the normal cleanup path: create one cleanup PR per repository to delete generated docs.

Activity Profiles

Only use these two profiles:

• vibe_coding_builder default
• active_personal_builder

Read references/activity-profiles.md for exact distributions.

Use deterministic randomness:

seed_text = f"{account}:{start_date}:{end_date}:{profile}:contributions-graph-filler-vp:v1"
seed = int(hashlib.sha256(seed_text.encode()).hexdigest()[:16], 16)
rng = random.Random(seed)

Allow a user-provided seed to override this value.

Planning Workflow

1. Confirm the skill was explicitly invoked.
2. Parse account, date range, profile, and execution mode.
3. Run preflight checks for gh, GitHub authentication, and API connectivity.
4. Scan repositories with gh repo list <account>.
5. Filter eligible repositories.
6. Enforce the > 10 eligible repository gate.
7. Generate active days by week using the selected profile.
8. Generate commit counts per active day.
9. Assign repositories with a bias toward project relevance and recent activity, while avoiding too many repositories per day.
10. Generate commit tasks matching each repository type.
11. Count existing author commits per planned active day and subtract them from the generated daily targets.
12. Output an Excel review file and stop for mandatory user approval.
13. In push-and-cleanup-pr, only after Excel approval, write durable files and create commits with both GIT_AUTHOR_DATE and GIT_COMMITTER_DATE.
14. Push the created commits to the GitHub default branch and verify remote reachability.
15. Create one cleanup branch per affected repository from the remote default branch.
16. Delete generated docs recorded in the manifest, commit the cleanup branch, push it, and open one draft PR per repository.
17. Verify all manifest-owned generated docs are absent from each cleanup PR branch.

Task Type Distribution

Use these task families:

["docs", "analysis", "eval", "chore", "tests", "config"]

Recommended weights:

[0.32, 0.22, 0.14, 0.14, 0.10, 0.08]

Repository-specific examples:

• ML/time-series: validation split notes, feature candidate notes, modeling assumptions, baseline evaluation checklist.
• RAG/LLM: retrieval evaluation notes, prompt routing checklist, regression assumptions, deployment review notes.
• Tooling/Agent: workflow boundaries, scoring criteria, local-first checklist, smoke test plan.
• Blog/knowledge base: reading notes, topic index, editorial backlog, comparison checklist.
• App/client: module boundary notes, API integration checklist, release checklist.

Bundled Script

Use scripts/generate_plan.py for deterministic plan generation:

python scripts/generate_plan.py --account VectorPeak --start 2026-03-01 --end 2026-04-01 --profile vibe_coding_builder --excel-out plan.xls

The script only generates a plan and Excel review file. It does not commit, push, or create cleanup PRs.

Default output is a daily table:

date    target_commit_count    existing_commit_count    planned_new_commit_count    commit_details

Use --granularity commit only when a downstream execution step needs one row per planned commit.

Output Requirements

For plan output, include:

• profile and seed;
• eligible repository count;
• total planned commits;
• Excel review file path;
• default daily table with date, target_commit_count, existing_commit_count, planned_new_commit_count, and commit_details;
• warnings for repository gate failures or excluded repositories.

For push-and-cleanup-PR execution summaries, include:

• repository path;
• branch;
• pushed commit SHA;
• remote verification status;
• cleanup branch;
• cleanup commit SHA;
• cleanup PR URL;
• deleted generated docs count;
• author date;
• message;
• whether the remote default branch contains the pushed commit before cleanup.