Skip to content

Commit 2cddfcc

Browse files
shepherdjerredshepherdjerred
committed
docs(dotfiles): plan agent skill release refresh
1 parent 060fec1 commit 2cddfcc

2 files changed

Lines changed: 184 additions & 0 deletions

File tree

‎packages/docs/logs/2026-08-03_locate-chezmoi-agent-skills.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
id: log-locate-chezmoi-agent-skills-2026-08-03
3+
type: log
4+
status: complete
5+
board: false
6+
---
7+
8+
# Locate Chezmoi Agent Skills
9+
10+
Confirmed with `chezmoi source-path ~/.agents/skills` that the managed source
11+
directory is `packages/dotfiles/dot_agents/skills`.
12+
13+
Of the 65 top-level managed skills, 32 (49.2%) contain a `What's New` section.
14+
These sections are static snapshots, commonly labeled 2024–2026, rather than
15+
automatically refreshed release feeds.
16+
17+
## Session Log — 2026-08-03
18+
19+
### Done
20+
21+
- Located the chezmoi-managed agent skills directory at
22+
`packages/dotfiles/dot_agents/skills`.
23+
- Confirmed the mapping with the live `chezmoi source-path` command.
24+
- Measured the release-oriented content: 32 of 65 skills contain a
25+
`What's New` section.
26+
27+
### Remaining
28+
29+
- None.
30+
31+
### Caveats
32+
33+
- `bun run check-todos` is currently blocked by the invalid frontmatter ID in
34+
the existing untracked file
35+
`packages/docs/logs/2026-08-03_scout-evals-populate-100-case-dataset.md`.
36+
- Release/version claims in skills are static Markdown and can become stale.

‎packages/docs/plans/2026-08-03_agent-skills-release-refresh.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
id: agent-skills-release-refresh
3+
type: plan
4+
status: in-progress
5+
board: true
6+
verification: agent
7+
disposition: active
8+
---
9+
10+
# Agent Skills Release Refresh
11+
12+
## Goal
13+
14+
Refresh the chezmoi-managed agent-skill corpus against current primary
15+
documentation, add missing high-value skills when the installed tool and
16+
repository inventory justify them, and retain only operationally useful,
17+
non-obvious guidance.
18+
19+
## Scope
20+
21+
Treat one top-level directory under `packages/dotfiles/dot_agents/skills/` as
22+
one researched item. Require at least 30 distinct, successfully fetched
23+
documentation pages for each of the 65 current skills. This produces a minimum
24+
of 1,950 fetched sources before follow-up research or newly added skills.
25+
26+
Commands, libraries, and features mentioned inside a skill are covered by that
27+
skill's 30-source set rather than treated as independent 30-source units.
28+
29+
## Research Questions and Source Strategy
30+
31+
1. Which existing claims are stale, removed, renamed, or incomplete? Use
32+
official release notes, versioned manuals, API references, and upstream
33+
repositories.
34+
2. Which new releases materially change agent behavior? Compare current stable
35+
releases with the newest version already covered by each skill.
36+
3. Which deprecated commands or unsafe examples should be removed? Verify
37+
against current command references, migration guides, schemas, and changelogs.
38+
4. Which missing workflows recur in the monorepo? Compare repository packages,
39+
installed tools, recent logs, and existing skill triggers.
40+
5. Which skills are too large for reliable loading? Apply progressive
41+
disclosure and move detailed reference material out of `SKILL.md` where it
42+
improves usability.
43+
6. Which internal workflow skills have drifted from live repository policy?
44+
Verify against the `AGENTS.md` hierarchy and current implementation.
45+
7. Which source claims disagree? Prefer current primary sources and record
46+
unresolved contradictions explicitly.
47+
8. Which updates survive independent forward tests? Give revised skills to
48+
clean-context agents using realistic tasks without leaking expected answers.
49+
50+
## Execution Model
51+
52+
- Create an isolated worktree from `origin/main` and initialize it as a native
53+
GitHub stack with `gh stack init --base main`.
54+
- Divide the corpus into disjoint research batches and rotate three concurrent
55+
subagents through them. Research agents must use Lightpanda first for page
56+
extraction, then `curl`/`wget`, and PinchTab only for blocked or interactive
57+
sites.
58+
- Require a source ledger per skill containing the visited URL, fetch method,
59+
retrieval result, source date/version when available, and distilled finding.
60+
- Keep source ledgers in repository working documentation rather than bloating
61+
the runtime skill context.
62+
- Edit skills only after the relevant 30-source threshold is met. Preserve
63+
durable workflows; replace release catalogs with concise current behavior and
64+
migration guidance.
65+
- Split the final change into cohesive native-stack layers by technology group
66+
if the diff is too large for one reviewable PR.
67+
68+
## Proposed Research Batches
69+
70+
1. Languages and runtimes: Bun, TypeScript, Go, Rust, Python, JVM, and Lua.
71+
2. Application frameworks and data tooling: Vite/React, Hono, XState, Zod,
72+
Prisma, ESLint, Satori, and Mastra.
73+
3. Containers and orchestration: Docker, Kubernetes, Helm, Argo CD, Talos,
74+
cdk8s, LinuxServer containers, storage, and deployment patterns.
75+
4. Infrastructure and networking: Terraform/OpenTofu, Tailscale, Grafana,
76+
OpenTelemetry, PagerDuty, Sentry, and Bugsink.
77+
5. Developer CLI and configuration: Git, GitHub, git-spice, worktrees, modern
78+
CLI tools, Fish, Zellij, chezmoi, 1Password, Lightpanda, and PinchTab.
79+
6. Product/API helpers: Buildkite, Discord, Riot/League, Apple HIG, Figma,
80+
Typst, and Xcode Cloud.
81+
7. Repository-native workflows: PR health/monitoring/automation, version
82+
management, review, reflection, grading, and monorepo documentation.
83+
8. Gap analysis: installed and repository-critical tools that lack a skill.
84+
85+
## Quality Gates
86+
87+
- Every refreshed skill has at least 30 successfully fetched source pages in
88+
the evidence ledger.
89+
- Every shipped URL is checked live and does not return a dead link.
90+
- Every factual release/version claim is traceable to a visited primary source.
91+
- Skill bodies remain concise and use progressive disclosure; detailed material
92+
belongs in directly linked `references/` files.
93+
- Existing user changes to `bugsink-helper/SKILL.md` are preserved and
94+
reconciled rather than overwritten.
95+
- Run skill validation for every changed or added skill.
96+
- Run focused formatting/link checks, `bun run check-todos`, and the staged
97+
pre-commit hook; fix all failures within the requested scope.
98+
- Run independent clean-context forward tests for representative revised skills
99+
and adversarial source review before publication.
100+
- Verify the chezmoi source/live mapping after the source changes. Do not apply
101+
repository state over the live skills without checking direction first.
102+
103+
## Remaining
104+
105+
- [x] Confirm that “30 sources” means per top-level skill, with commands and
106+
libraries inside that skill covered by the same 30-source set.
107+
- [x] Create and initialize the isolated native-stack worktree.
108+
- [ ] Inventory the full corpus, existing references, current versions, and
109+
missing high-value skills.
110+
- [ ] Run the multi-agent research batches and build the per-skill evidence
111+
ledger.
112+
- [ ] Reconcile overlapping and contradictory findings.
113+
- [ ] Refresh existing skills and add justified missing skills.
114+
- [ ] Validate links, skill structure, focused checks, docs, and chezmoi drift.
115+
- [ ] Forward-test representative skills with clean-context agents.
116+
- [ ] Publish the reviewable native GitHub stack with source and verification
117+
evidence.
118+
119+
## Comment Log
120+
121+
- 2026-08-03: Initial corpus inventory found 65 top-level skills; 32 currently
122+
contain a `What's New` section. The main checkout also contains an active
123+
user change to `bugsink-helper/SKILL.md`, which must be preserved.
124+
- 2026-08-03: The user confirmed the 30-source requirement applies per
125+
top-level skill. Created `.claude/worktrees/agent-skills-refresh` on
126+
`feature/agent-skills-refresh` and initialized it with native `gh stack`.
127+
128+
## Session Log — 2026-08-03
129+
130+
### Done
131+
132+
- Loaded the skill-authoring, deep-research, Lightpanda, chezmoi, worktree,
133+
native GitHub stack, Git, and monorepo-documentation guidance.
134+
- Inventoried 65 top-level managed skills and identified the existing Bugsink
135+
overlap that must be preserved.
136+
- Confirmed the 30-source-per-top-level-skill scope with the user.
137+
- Created and initialized the isolated native-stack worktree.
138+
139+
### Remaining
140+
141+
- Complete all research, implementation, verification, forward-testing, and
142+
publication work.
143+
144+
### Caveats
145+
146+
- `bun run check-todos` in the main checkout stopped on the invalid frontmatter
147+
ID in the existing untracked file
148+
`packages/docs/logs/2026-08-03_scout-evals-populate-100-case-dataset.md`.

0 commit comments

Comments
 (0)