tentaflake-change-review
starsforks
How to install tentaflake-change-review?
timfewi/tentaflake/tentaflake-change-review
$npx -y skills add timfewi/tentaflake --skill tentaflake-change-reviewLightweight change-review discipline for the tentaflake repo — require a linked reason (issue/requirement), a verification step, and doc sync before any change is called done. Use when planning, implementing, or reviewing a change to the template.
SKILL.md
| 1 | # Tentaflake — Change Review |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | A deliberately small verification discipline for changes to the tentaflake |
| 6 | template. It borrows one idea from heavyweight AI-engineering frameworks — |
| 7 | **traceability: every change ties back to a reason and forward to a check** — |
| 8 | but strips the ceremony (no ISO matrices, no multi-cycle lifecycle, no |
| 9 | red-team gates). It is sized for a ~30-file NixOS template maintained by |
| 10 | Conventional Commits + PRs. |
| 11 | |
| 12 | The goal: stop "orphaned" changes (code with no stated reason), silent |
| 13 | assumptions, and doc drift — without slowing ordinary work. |
| 14 | |
| 15 | ## When to use |
| 16 | |
| 17 | - Planning any non-trivial change (new module, option, lib arg, script, CI step). |
| 18 | - Implementing a bug fix or feature. |
| 19 | - Reviewing a diff before opening or merging a PR. |
| 20 | |
| 21 | Skip it for pure formatting, typo fixes, or comment-only edits. |
| 22 | |
| 23 | ## The three gates |
| 24 | |
| 25 | Every change must clear three gates before it is "done". State them explicitly |
| 26 | in your plan and in the PR description. |
| 27 | |
| 28 | ### 1. REASON — why does this change exist? |
| 29 | |
| 30 | Link the change to one of: |
| 31 | |
| 32 | - an existing GitHub issue (`gh issue view <n>`), |
| 33 | - a bug reproduced with a concrete command/output, or |
| 34 | - a one-sentence requirement written *before* the code. |
| 35 | |
| 36 | If you cannot name the reason, do not write the code. A change whose only |
| 37 | justification is "seemed nice" is an orphan — either write the requirement |
| 38 | first or drop it. |
| 39 | |
| 40 | > Anti-pattern: adding a `tentaflake.*` option "just in case". Options are API |
| 41 | > surface; each one needs a stated need and a default that keeps existing |
| 42 | > configs working. |
| 43 | |
| 44 | ### 2. VERIFY — how do we know it works? |
| 45 | |
| 46 | Name the check *before* implementing, and actually run it. Pick the tightest |
| 47 | applicable command from the repo's real toolchain: |
| 48 | |
| 49 | | Change touches | Verification | |
| 50 | |---|---| |
| 51 | | Any `.nix` (module/lib/config) | `nix flake check` | |
| 52 | | Host config / new option | `nix build .#nixosConfigurations.tentaflake.config.system.build.toplevel --no-link` (the attr follows `constants.hostName`) | |
| 53 | | Runtime behavior (unit, state dir, CLI) | `nix build .#checks.x86_64-linux.vm-integration -L` | |
| 54 | | Container image pin | `nix build .#checks.x86_64-linux.image-pinning` | |
| 55 | | Formatting | `nix fmt` (CI runs `nix fmt -- --ci`) | |
| 56 | | Go (`pkgs/tentaflake-auditd`) | `go build ./... && go vet ./... && go test ./...`, then `golangci-lint run` | |
| 57 | | Shell scripts | `shellcheck installer/*.sh scripts/*.sh` | |
| 58 | | Login banner | `./scripts/banner-test.sh` | |
| 59 | | Installer-generated flake | `./scripts/generated-flake-test.sh` | |
| 60 | | ISO changes | `nix build .#installer-iso` / `nix build .#live-agent-iso` | |
| 61 | |
| 62 | Prefer a fresh check over self-grading: don't just assert "it builds" — paste |
| 63 | the command you ran. If a behavior can't be exercised by an existing check, |
| 64 | add or extend a check (e.g. a Go test) as part of the same change. |
| 65 | |
| 66 | > Anti-pattern: "passed all tests" when the change added no test and no |
| 67 | > existing test covers the new path. |
| 68 | |
| 69 | ### 3. SYNC — what else must move with it? |
| 70 | |
| 71 | Per `AGENTS.md`, a change that alters behavior, options, or usage is not done |
| 72 | until its docs move in the same change. Check each surface: |
| 73 | |
| 74 | - `README.md` and `docs/` — user-facing behavior/options. |
| 75 | - `AGENTS.md` / `CLAUDE.md` — agent instructions. |
| 76 | - `.agents/skills/tentaflake-repo-guidance/SKILL.md` — option tables, lib args, |
| 77 | module reference (this is the map agents rely on; stale entries mislead). |
| 78 | - Relevant `.agents/skills/` — if you touched a subsystem a skill documents. |
| 79 | - `my-agents.nix.example` / `*.env.example` — if you changed agent args or env. |
| 80 | - `CHANGELOG.md` — add the entry under `## [Unreleased]`, in the section that |
| 81 | fits (`⚠ Breaking` / `Security` / `Added` / `Changed` / `Fixed`). This |
| 82 | changelog explains *why*, not just what — match the surrounding voice. |
| 83 | |
| 84 | ## Traceability (the through-line) |
| 85 | |
| 86 | The three gates only pay off if the links between them are *recorded*, not just |
| 87 | thought about. Keep a single, lightweight chain per change: |
| 88 | |
| 89 | ``` |
| 90 | REASON (issue/requirement) → ART (the commit/diff) → CHECK (verification) |
| 91 | ``` |
| 92 | |
| 93 | You don't need a separate matrix file — git and GitHub already store the chain |
| 94 | if you populate them: |
| 95 | |
| 96 | - **REASON → ART:** reference the issue in the commit body and PR |
| 97 | (`Closes #NN`, or `Refs: <one-line requirement>` when there's no issue). |
| 98 | GitHub then back-links the commit/PR to the issue automatically. |
| 99 | - **ART → CHECK:** name the verification command in the commit/PR body |
| 100 | (`Verified: nix flake check`) and, where the behavior is testable, add the |
| 101 | test in the *same* commit so the artifact and its check live together. |
| 102 | - **One change = one chain.** Keep unrelated reasons in separate commits/PRs so |
| 103 | each link is unambiguous. A commit that closes three unrelated issues has no |
| 104 | clean t |
People who liked this also viewed
6 picksType
- requesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirementsSkillsJul 2026
- code-reviewSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- receiving-code-reviewUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performativeSkillsJul 2026
- baoyu-format-markdownFormats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or imprSkillsJul 2026
- code-review-excellenceMaster effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing reSkillsJul 2026
- code-review-and-qualityConducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensiSkillsJul 2026
