@groupby/ai-dev 0.5.1 → 0.5.4

package/teams/snpd/skills/docs-init-v2/SKILL.md

@@ -1,402 +0,0 @@
----
-name: docs-init-v2
-description: Use when the user wants to initialize or refresh the canonical `/docs` folder, `CLAUDE.md`, and `README.md` based on the current repo state. Creates the five canonical docs if missing; audits them for drift against the code if present. Triggered by `/docs-init-v2` or requests like "update the docs v2", "create the docs v2", "refresh project documentation v2", "init docs v2".
----
-
-# docs-init
-
-Initialize or refresh project documentation. Works in two modes automatically:
-
-- **Init mode** — `/docs` is missing or incomplete. Create the canonical
-  five-file structure from a fresh repo scan.
-- **Refresh mode** — `/docs` exists. Audit each file against the current
-  code and report what is outdated, drifted, or newly worth documenting.
-  Apply updates only after the user approves the human-readable report.
-
-## The Canonical Structure
-
-```text
-README.md                ← 30-second landing page + links into docs/
-CLAUDE.md                ← thin index for AI agents
-docs/
-  architecture.md        ← system, packages, domain model, cross-cutting concerns
-  local-setup.md         ← prerequisites, run, test, troubleshooting
-  conventions.md         ← code style, testing, API, migrations, PR norms
-  operations.md          ← deploy, secrets, observability, runbooks
-  decisions.md           ← append-only "why" log (ADR-lite)
-```
-
-Every doc under `docs/` MUST start with a `> **Scope:**` block explaining
-what belongs there, what does not, and where it is referenced from.
-Preserve this block on every edit.
-
-## Procedure
-
-### 1. Detect mode
-
-- Check for `README.md`, `CLAUDE.md`, and each of the five `docs/*.md` files.
-- If three or more are missing → **init mode**.
-- Otherwise → **refresh mode**.
-- **Exception:** If canonical files are missing but the repo has substantial
-  existing documentation (e.g. `docs/` with other files, detailed README,
-  wiki-style markdown), treat as **refresh mode** — bridge existing docs
-  into the canonical structure rather than creating from scratch. Mention
-  existing docs in the report and propose how to integrate or link them.
-- Announce the detected mode to the user before proceeding.
-
-### 2. Scan the repo
-
-Gather facts from the actual code, not assumptions:
-
-- **Stack & build:** `build.gradle` / `pom.xml` / `package.json` /
-  `Cargo.toml` / `go.mod` / `pyproject.toml` / `setup.py` /
-  `requirements.txt` / `Makefile` / equivalent — language version,
-  framework, key libraries.
-- **Run commands:** README scripts, build-tool tasks (`./gradlew tasks`,
-  `npm run`, `make`, `cargo`, `go`, `pytest`, etc.), `docker-compose.yml`.
-- **Package layout:** top-level dirs under `src/` (or `lib/`, `app/`,
-  `cmd/`, `internal/`, `pkg/` for Go, `dags/`/`jobs/` for Airflow,
-  `packages/`/`apps/` for monorepos, `manifests/` for infra repos).
-- **Domain types:** entity/model/record/struct/schema classes; group by
-  package or module.
-- **Tests:** test framework, conventions, fixture locations.
-- **Migrations:** Flyway / Liquibase / Alembic / Knex / equivalent paths
-  and naming.
-- **CI/CD:** files under `.github/workflows/`, `.circleci/`, `Jenkinsfile`,
-  `cloudbuild.yaml`, or equivalent. Note the CI system in use.
-- **Deploy:** `helm/`, `k8s/`, `kustomize/`, `terraform/`, Dockerfile,
-  `Procfile`, Argo CD manifests.
-- **Observability:** OpenTelemetry / logging / Prometheus / Datadog config.
-- **Secrets:** Vault references, sealed-secrets, workload identity, ADC,
-  env var injection.
-- **API surface:** controller annotations, OpenAPI spec, route definitions,
-  proto definitions, GraphQL schema.
-
-For refresh mode, also collect `git log --since="<doc-mtime>"` per doc to
-narrow attention to changes the doc may not yet reflect.
-
-### 3a. Init mode — draft (do NOT write yet)
-
-Draft the seven files in memory using the canonical templates below. Every
-`docs/` file starts with the `Scope` block. Leave honest placeholders where
-the repo does not yet have the answer (e.g. operations runbooks, dashboard
-links). Do not fabricate.
-
-**Verification checklist — apply to every claim before including it:**
-
-1. **Commands** — Before writing any `./gradlew <task>`, `npm run <script>`,
-   `make <target>`, `go <cmd>`, or similar, confirm the task exists (check
-   `build.gradle` tasks, `package.json` scripts, Makefile targets, workflow
-   files). Never guess task names.
-2. **Config keys** — Quote exact property paths from the actual config file
-   (YAML, properties, JSON, TOML, `.env`, Helm values, Kustomize overlays).
-   Do not paraphrase or use placeholder syntax like `${...}`.
-3. **Directory contents** — List (`ls`) the directory before describing what it
-   contains. Never say "contains templates only" or "contains X" without
-   checking.
-4. **Credentials** — Never instruct placing credentials in a repo-tracked file.
-   Recommend user-home config instead: `~/.gradle/gradle.properties`,
-   `~/.m2/settings.xml`, `~/.npmrc`, `~/.pypirc`, `~/.docker/config.json`,
-   or environment variables / Application Default Credentials (ADC).
-5. **Submodule commands** — Use `git submodule update --init --recursive`
-   (pinned commit). Never use `--remote` (breaks reproducible builds).
-6. **CI/CD triggers** — Read the actual trigger/filter syntax for the CI system
-   in use (GitHub Actions `on:` block, CircleCI `filters:`, Jenkins pipeline
-   triggers, etc.). List all branches/events accurately.
-7. **Scope qualifiers** — When stating "all X do Y," verify there are no
-   exceptions (e.g. health, metrics, actuator endpoints outside the API prefix).
-8. **File references** — When describing what a file is used for, trace its
-   references (grep for the filename) so the description matches actual usage.
-
-Targets: `CLAUDE.md` ≤ 40 lines, `README.md` ≤ 30 lines.
-
-**Do not write these files to disk yet.** Continue to step 4, where the
-draft contents are summarized in the audit report and the user approves
-before any file is created.
-
-### 3b. Refresh mode — audit each file
-
-For each existing doc, classify findings into three buckets:
-
-- **Outdated** — the doc states something that is no longer true (a removed
-  command, a renamed package, a retired workflow, a wrong version number).
-- **Drifted** — the doc is technically correct but missing material the
-  code now contains (a new package, a new build task, a new workflow, a
-  new env profile).
-- **New opportunities** — content the doc does not have but probably
-  should (a recently added feature area, a new observability surface).
-
-`decisions.md` is **append-only**: propose new entries on approval, but
-never rewrite or remove existing ones.
-
-### 4. Report to the user (human-friendly, NOT a diff)
-
-In **init mode**, the report summarizes what each new file will contain
-(one paragraph per file describing scope and key sections drafted), and
-the "Proposed actions" list reads as `Create <path>` items.
-
-In **refresh mode**, the report follows the per-file findings format
-below.
-
-Output a single readable report in this exact shape:
-
-```markdown
-# Documentation audit — <YYYY-MM-DD>
-
-Mode: <init | refresh>
-
-## Summary
-<2-3 sentences: what was created or what needs attention overall>
-
-## Per-file findings
-
-### docs/architecture.md
-**Outdated:**
-- The package list mentions `legacy/` but that directory was removed in <commit>.
-- Lists framework version X.Y; build file now pins X.Z.
-
-**Drifted:**
-- A new top-level package is not mentioned.
-
-**New opportunities:**
-- A retry strategy was added in <PR>; worth a short paragraph.
-
-### docs/local-setup.md
-**Outdated:**
-- (none)
-
-**Drifted:**
-- A new build/test task was added in <commit> but the doc does not list it.
-
-(... continue for each file ...)
-
-### CLAUDE.md
-**Outdated:** (none)
-**Drifted:** Pointer to `docs/operations.md` is missing.
-
-### README.md
-**Outdated:** Quick-start references an old env-var value that has been
-renamed.
-
-## Proposed actions
-
-Numbered list of concrete edits I would make if you approve. Group by
-file. Each item is one sentence — no diffs.
-
-## Verified against source
-
-List what was checked to ensure accuracy:
-- Commands: <which tasks were confirmed and how>
-- Config keys: <which files were read for exact property names>
-- Directories: <which directories were listed>
-- Workflow triggers: <which workflow files were read>
-- Credentials: <confirm no repo-tracked file instructions>
-
-## Awaiting your approval
-
-Reply "apply" to make the changes, "apply <numbers>" to apply a subset
-(e.g. "apply 1,3,5"), or "skip" to make no changes.
-```
-
-If a bucket is empty for a file, write `(none)` — do not omit the bucket.
-This makes it obvious that the check ran.
-
-### 5. Apply on approval
-
-- On `apply` — create or edit each affected file. In init mode this means
-  creating all seven files from the drafts in step 3a. In refresh mode
-  it means editing existing files in place. Preserve `Scope` blocks. Do
-  not reorganize content across files. Do not change file names.
-- On `apply <numbers>` — apply only the selected proposed actions.
-- On `skip` — make no edits or creations; thank the user and exit.
-- After applying, print a short summary of which files were created or
-  changed and suggest a commit message.
-
-## Hard rules
-
-- **Apply edits only after explicit user approval.** No file under `docs/`,
-  `CLAUDE.md`, or `README.md` is edited before the user replies `apply` or
-  `apply <numbers>`.
-- **`decisions.md` is append-only.** New entries may be added on approval;
-  existing entries are never edited or removed.
-- **Preserve every `> **Scope:**` block** verbatim on edited docs.
-- **Do not move content between files.** Each file's scope is the
-  convention. If content does not fit any of the five, mention it in the
-  report and ask whether to create a new file or fold it elsewhere.
-- **Do not fabricate.** If the repo has no dashboards, no runbooks, no
-  decisions yet, leave honest placeholders or empty sections.
-- **Verify every factual claim.** Before including any command, config key,
-  directory description, or workflow trigger in the docs, confirm it against
-  the actual source file. See the verification checklist in step 3a.
-- **Never reference repo-tracked files for credentials.** Always use
-  user-home paths (`~/.gradle/gradle.properties`, `~/.m2/settings.xml`,
-  `~/.npmrc`, `~/.pypirc`) or environment variables / ADC.
-- **Never use `--remote` in submodule commands.** Use pinned commits for
-  reproducible builds.
-- **Qualify universal statements.** If writing "all endpoints do X," verify
-  there are no exceptions and add qualifiers if needed.
-- **Do not delete sections without flagging them.** Surfacing a removal
-  belongs in the report, not as a silent edit.
-- **Do not edit `.github/PULL_REQUEST_TEMPLATE.md`, CI files, or code.**
-  This skill only touches docs.
-- **Keep `CLAUDE.md` ≤ 40 lines and `README.md` ≤ 30 lines** after edit.
-  If pointers no longer fit, ask before expanding.
-
-## Canonical templates
-
-When in init mode, use these skeletons. Fill from the repo scan.
-
-### `docs/architecture.md`
-
-```markdown
-# Architecture
-
-> **Scope:** What this system is, how it's structured, and the domain it models.
-> Put here: tech stack, package/module layout, key components, domain entities,
-> cross-cutting concerns (auth, multi-tenancy, observability).
-> Do **not** put here: how to run it (→ local-setup.md), how to deploy it
-> (→ operations.md), code style (→ conventions.md).
->
-> **Referenced from:** `README.md` and `CLAUDE.md`.
-
-## Overview
-## Package Structure
-## Key Libraries
-## Domain Model
-## Cross-Cutting Concerns
-```
-
-### `docs/local-setup.md`
-
-```markdown
-# Local Setup
-
-> **Scope:** Everything needed to clone, run, and test on a fresh machine.
-> Put here: prerequisites, full setup steps, env vars, build/test commands,
-> troubleshooting.
-> Do **not** put here: deployment (→ operations.md), architecture
-> (→ architecture.md).
->
-> **Referenced from:** `README.md` quick-start (links here for detail) and `CLAUDE.md`.
-
-## Prerequisites
-## Run the Service
-## Common Tasks
-## Environment Profiles
-## Troubleshooting
-```
-
-### `docs/conventions.md`
-
-```markdown
-# Conventions
-
-> **Scope:** How we write and review code in this repo.
-> Put here: language conventions, testing philosophy, naming rules, API
-> rules, migration rules, PR norms.
-> Do **not** put here: architecture (→ architecture.md), ops (→ operations.md).
->
-> **Referenced from:** `CLAUDE.md` (so AI agents follow these) and `README.md`.
-
-## Code Style
-## Testing
-## API Conventions
-## Database Migrations
-## PRs and Commits
-```
-
-### `docs/operations.md`
-
-```markdown
-# Operations
-
-> **Scope:** What happens after merge — deploy, run, observe, recover.
-> Put here: deploy pipelines, environments, secrets source, dashboards,
-> alerts, runbooks.
-> Do **not** put here: architecture (→ architecture.md), local dev
-> (→ local-setup.md).
->
-> **Referenced from:** `README.md` and `CLAUDE.md`.
-
-## Deploy
-## Secrets
-## Observability
-## Common Runbooks
-## On-Call
-```
-
-### `docs/decisions.md`
-
-```markdown
-# Decisions
-
-> **Scope:** Short, append-only log of *why* this codebase is the way it is.
-> Captures decisions whose rationale is not obvious from reading the code.
-> Put here: framework choices, trade-offs taken, deliberate deviations.
-> Do **not** put here: how-to instructions, code-level comments.
->
-> **Referenced from:** `CLAUDE.md`, and linked from PRs that introduce a
-> non-obvious choice.
-
-## Format
-
-Append a new entry as a new top-level section. Don't edit prior entries —
-if a decision is reversed, add a new entry that supersedes the old one.
-
-Each entry:
-- **Context:** what prompted the decision
-- **Decision:** what we chose
-- **Consequence:** what this means going forward (and what we're giving up)
-
-## Entries
-
-*(No entries yet.)*
-```
-
-### `CLAUDE.md`
-
-```markdown
-# CLAUDE.md
-
-Index for AI coding agents (Claude Code, Copilot CLI). Keep this file short —
-point to `docs/` for substance.
-
-## What this repo is
-
-<one-paragraph description from the repo scan>
-
-## Where things live
-
-- **Architecture, domain model, package layout** → [docs/architecture.md](docs/architecture.md)
-- **Build / run / test commands** → [docs/local-setup.md](docs/local-setup.md)
-- **Code style, testing conventions, API/migration rules** → [docs/conventions.md](docs/conventions.md)
-- **Deploy, secrets, observability, runbooks** → [docs/operations.md](docs/operations.md)
-- **Why things are the way they are** → [docs/decisions.md](docs/decisions.md)
-
-## Rules for working in this repo
-
-<3-6 short bullets — only repo-specific gotchas an agent must follow on
-every turn. Do not duplicate detail that lives in docs/>
-```
-
-### `README.md`
-
-```markdown
-# <repo name>
-
-<one-paragraph description>
-
-## Quick start
-
-<3-5 lines: the shortest possible happy path>
-
-Requires <prereqs>. For detail see [docs/local-setup.md](docs/local-setup.md).
-
-## Documentation
-
-- [Architecture](docs/architecture.md) — system overview, domain model, package layout
-- [Local setup](docs/local-setup.md) — full setup, tasks, troubleshooting
-- [Conventions](docs/conventions.md) — code style, testing, API & migration rules
-- [Operations](docs/operations.md) — deploy, secrets, observability, runbooks
-- [Decisions](docs/decisions.md) — why things are the way they are
-```