diff --git a/.gitignore b/.gitignore index fe21d4d..afdd1cb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ .DS_Store .idea -/node_modules +node_modules/ /docs \ No newline at end of file diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 37348b3..0d0b77d 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -1,6 +1,6 @@ { "$schema": "./node_modules/oxfmt/configuration_schema.json", - "ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"], + "ignorePatterns": ["**/node_modules/**"], "printWidth": 80, "proseWrap": "preserve", "tabWidth": 4, diff --git a/.oxlintrc.json b/.oxlintrc.json index 70d4f7c..15bede7 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -4,7 +4,7 @@ "correctness": "error", "suspicious": "error" }, - "ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"], + "ignorePatterns": ["**/node_modules/**"], "options": { "denyWarnings": true, "reportUnusedDisableDirectives": "error", diff --git a/AGENTS.md b/AGENTS.md index 4321b5f..5dd4ffa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,5 @@ -- When a user correction establishes a reusable repository-wide rule, ask whether to invoke `$maintain-agents` to add it. -- When authoring or reviewing a skill, include only runtime instructions and knowledge for its agent; exclude authoring rationale, evaluation history, and composition discussion, and justify behaviour only with runtime-available context. -- When eliciting within a software project, invoke `$elicit-with-context` instead of `$elicit`; use `$elicit` directly only for non-software work or as part of `$elicit-with-context`. -- When composing skills, rely on each invoked skill's public contract; do not restate or steer its internal logic. -- Default to a user-agent workflow; introduce team roles, named accountable people, approval bodies, or third-party coordination only when the user or project evidence requires them. +- When a user correction establishes a durable project-wide instruction needed in every session, ask whether to invoke `$maintain-agents` to add it. +- When creating, reviewing or maintaining skills, invoke `$write-skill`. +- Default to a user-agent workflow; do not introduce team roles, named accountable people, approval bodies, or third-party coordination. - Assume the execution harness supports fresh agents; do not add fallback handling for their unavailability. - After implementing changes run `bun run checks` before handoff. diff --git a/GLOSSARY.md b/GLOSSARY.md index 984a19d..570ddb9 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -2,38 +2,22 @@ ## Language -### Skill model +### Skill invocation -**Predictability**: The degree to which a skill makes the agent follow the same process on every run, without requiring the same output. +**Lifecycle entry point**: A skill a user invokes to begin a common software delivery task, such as product definition, ticket planning, implementation or maintenance. Users can start at the entry point that matches their available context and desired outcome. -**User-invoked skill**: A skill the user selects explicitly. This is Propulsion's default invocation mode. +**Supporting skill**: A skill that supplies a focused capability to a lifecycle entry point through composition. Users can also invoke supporting skills directly when they need that capability. -**Model-invoked skill**: A skill the agent may select autonomously or invoke from another skill. Use this exception only when autonomous discovery would naturally help during ordinary coding work often enough to earn its permanent context cost. +**Breadth-first planning**: Establish product scope before detailing individual features, then break a selected feature into small executable tickets. Each level narrows the work without making earlier levels mandatory for an understood task. -**Invocation policy**: Client-specific metadata within a skill bundle that controls whether an agent may select that skill implicitly. The same intent may require different policy fields in different clients. +**Explicit invocation**: A skill is selected by name in the request. This is Propulsion's default entry mode. -### Skill types +**Implicit invocation**: The agent selects a skill without a named request because its trigger applies. -**Skill type**: The authority category recorded in a skill's frontmatter as `metadata.type`. Propulsion uses exactly `performer`, `router`, `teaching`, or `utility`. +**Composed invocation**: A skill invokes another skill as part of its workflow, using the called skill's public contract. Composition is distinct from implicit selection. -**Performer skill**: Owns one bounded requested outcome end to end, including its actions, artefacts, verification, handoff, and stopping boundary. - -**Router skill**: Resolves the inputs needed to coordinate other skills and returns their results. It contains only routing unique to that outcome; called skills remain authoritative and the router neither repeats nor overrides their context. - -**Teaching skill**: Supplies knowledge and decision rules inside a caller's workflow. It does not own an independent operation, mutation, artefact, verification, handoff, or stopping decision. - -**Utility skill**: Owns one bounded reusable operation and returns its result, whether the operation runs in the calling agent, a fresh agent, or a deterministic tool. +**Duplicated procedure**: A composing skill or supporting resource repeats execution rules owned by a skill it delegates to. Caller-specific inputs, sequencing, authority boundaries and outcome checks define composition rather than duplicated procedure. ### Software quality **Deterministic measurement**: A reproducible tool-produced observation of one named property of a fixed software candidate, with its scope, components, configuration, limitations, and comparison basis preserved. An attention threshold requires appraisal but is not by itself a defect, an overall quality score, or permission to weaken behaviour or design. - -### Skill benchmarking - -**Authentic workflow arm**: One isolated benchmark run that gives a skill set the same implementation task, starting repository, model, tools, permissions, and environment as the other arms while allowing it to load and follow its own required skills and workflow. - -**Adaptive single-run comparison**: One fresh run per benchmark arm, followed by another run only for an arm whose result is tied, failed, or surprising enough that run-to-run variation could materially change the conclusion. - -**Skill-context tokens**: The exact tokenizer count of a benchmark arm's skill discovery metadata and every skill or reference file loaded during the run, reported separately from whole-run model usage. - -**Runtime token usage**: The execution harness's complete input, cached-input, output, and reasoning-output token counts for one benchmark arm, excluding the independent quality evaluator. diff --git a/README.md b/README.md index 78cd26a..1b107c8 100644 --- a/README.md +++ b/README.md @@ -2,184 +2,128 @@ # Propulsion -Propulsion is a compact, composable set of Agent Skills for practical software delivery. It supports the realistic lifecycle around coding—from establishing a product and defining features to creating tickets, implementation, and debugging. +Propulsion is a set of composable Agent Skills for software delivery, from product definition and planning to implementation, review and maintenance. -Each skill runs one bounded working session and stops with an independently useful outcome. You can enter wherever the necessary inputs already exist and leave when that outcome is complete. +Each skill has a narrow scope and a clear outcome. Lifecycle entry points bring supporting skills together, so you can ask for an outcome without managing every step yourself. -Substantial work narrows breadth-first over several sessions: product intent becomes a decision-complete feature specification, then implementation-ready tickets, and finally one implemented body of work per ticket. Small, understood work can begin directly with `$implement`. +Planning works breadth-first. Establish the product's scope, explore a selected feature, then break it into small executable tickets. Start wherever you have enough context. A small, understood change can go straight to `$implement`. ## Installation -### Remote +### Skills CLI -Install Propulsion from GitHub with the skills installer: +Install the full set with the [Skills CLI](https://github.com/vercel-labs/skills), including the supporting skills used by lifecycle entry points: ```sh -bunx skills@latest add moonpixels/propulsion +bunx skills@latest add moonpixels/propulsion --skill '*' ``` -Choose the skills and coding agents you want when prompted. +Choose your coding agents when prompted. Add `--global` to make the skills available across projects. -### Local +### Local symlinks -When developing Propulsion from a local clone, link each skill you want to use into the shared Agent Skills directory: +From the root of a local Propulsion clone, link the skills into the shared Agent Skills directory: ```sh -mkdir -p ~/.agents/skills -ln -s /absolute/path/to/propulsion/skills/elicit ~/.agents/skills/elicit +mkdir -p "$HOME/.agents/skills" +for skill_path in "$PWD"/skills/*; do + ln -s "$skill_path" "$HOME/.agents/skills/" +done ``` -Repeat the link for each selected skill. Codex and OpenCode both discover skills from `~/.agents/skills`; edits in the clone are available through the links without reinstalling or publishing a new version. +Use this with clients that discover `~/.agents/skills`. Edits in the clone are available through the links without reinstalling. -## Lifecycle skills +## Lifecycle entry points -The lifecycle areas below are independent entry points, not mandatory phase gates. Invoke the skill for the outcome you need, later stages do not start automatically. +Choose the skill for the outcome you need. Each invocation finishes its own task. You decide when to move to the next one. -### Establish +| Skill | Start here to… | +| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| [$define-product](skills/define-product/SKILL.md) | Explore a new app idea or revisit an existing product. Establish its goals, journeys, shared requirements and feature index in `PRODUCT.md`. | +| [$specify-feature](skills/specify-feature/SKILL.md) | Define one feature's behaviour, acceptance examples and consequential technical choices. Produce a specification ready for ticket planning. | +| [$create-tickets](skills/create-tickets/SKILL.md) | Break requested work into small vertical slices. Create executable tickets with acceptance criteria and dependencies. | +| [$implement](skills/implement/SKILL.md) | Deliver a ticket or another understood change. Produce a minimal local implementation with applicable checks, simplification and independent review. | +| [$commit](skills/commit/SKILL.md) | Record all uncommitted branch changes in atomic Conventional Commits. | +| [$pull-request](skills/pull-request/SKILL.md) | Publish the branch for review. Commit any remaining changes, push the branch, and create or update its pull request. | +| [$review-pull-request](skills/review-pull-request/SKILL.md) | Independently assess an existing PR against engineering standards and available requirements. Return findings for you to act on. | +| [$debug](skills/debug/SKILL.md) | Investigate a failure and establish its cause. Ask for diagnosis alone or a repair with implementation and verification. | +| [$upgrade-dependencies](skills/upgrade-dependencies/SKILL.md) | Update dependencies and build or CI tooling through checked migrations. Include language or runtime upgrades when requested. | -#### `$define-product` +## Example workflow -Enter here to establish or deliberately revise the product and system requirements foundation: +Imagine building **Shelf**, a personal reading list app. The following prompts follow the same idea from planning to maintenance. Use each in a separate session when you are ready, replacing the illustrative document, ticket and PR references with your own. -```text -$define-product -``` - -The session produces a user-confirmed `PRODUCT.md` and the corresponding project language in `GLOSSARY.md`. It stops before defining individual features, selecting feature-specific architecture, or creating tickets. - -### Define - -#### `$specify-feature` - -Enter here when a high-level feature request needs enough behavioural and technical definition for planning: +Start with the whole app, then select its first feature: ```text -$specify-feature +$define-product Shelf, an app for saving books I want to read and tracking my progress ``` -The session produces one approved, decision-complete feature specification containing visibly distinct feature intent and selected solution sections. No earlier lifecycle artefact is mandatory, and the skill stops before ticket creation or implementation. - -### Plan - -#### `$create-tickets` - -Enter here when an approved document or confirmed conversation is complete enough to decompose without inventing behaviour or material solution decisions: - ```text -$create-tickets +$specify-feature the reading list in @PRODUCT.md, including adding books and marking them as read ``` -The session creates and verifies small, vertically sliced, dependency-aware tickets with Fibonacci complexity in the destination named by the project's root `AGENTS.md`. It stops before scheduling or implementing them. - -Local Markdown destinations use one file per ticket under `docs/features//tickets/`. External destinations use their native items, estimates, relationships, and statuses. If `AGENTS.md` does not name the destination, the skill asks and records it. - -### Refine - -#### `$review-architecture` - -Enter here to assess an explicitly bounded part of the current architecture: +Turn the feature into tickets, then implement them in dependency order. For example, start with the ticket for adding a book: ```text -$review-architecture +$create-tickets for @docs/features/reading-list/specification.md ``` -The session produces an evidence-backed report containing a small number of prioritised, high-value improvements and their trade-offs. It does not refactor the code or create speculative tickets. - -### Deliver - -#### `$implement` - -Enter here with one ticket or another small, confirmed body of work: - ```text -$implement +$implement @docs/features/reading-list/tickets/TKT-007-add-book.md ``` -The session produces a minimal local change with retained tests, applicable quality evidence, and completed independent review. Small, understood work can begin here without a product definition, feature specification, or ticket. Implementation does not commit or publish the change. - -`$implement` applies `$modular-design`, uses `$tdd` for behaviour-changing work when a usable suite can exercise it, and requires an independent `$code-review`. `$tdd` applies the reusable `$test-design` teaching for durable behavioural tests. Implementation uses existing project infrastructure and reports unavailable evidence instead of installing unrelated tooling or manufacturing confidence. - -#### `$commit` - -Enter here when eligible reviewed work is ready to be recorded: +Record completed work when it forms a coherent unit. Publish the branch when it is ready for review: ```text $commit ``` -The session creates and verifies coherent Conventional Commits while preserving unrelated staged, unstaged, and untracked work. It does not push or open a pull request. - -#### `$pull-request` - -Enter here when the current branch is ready to publish for human review: - -```text -$pull-request -``` - -The session commits eligible remaining work when needed, pushes the branch, and creates or updates one pull request describing the complete branch. It does not merge, release, or deploy the work. - -A substantial feature commonly moves through separate sessions: - -```text -$specify-feature - → later $create-tickets - → $implement each selected ticket - → $commit whenever a coherent unit is ready - → $pull-request when the branch is ready -``` - -A small, understood change may start later: - ```text -$implement → $commit → $pull-request +$pull-request for Shelf's reading list feature ``` -### Upgrade - -#### `$upgrade-dependencies` - -Enter here to upgrade package dependencies or the project's full toolchain: +Review the resulting PR: ```text -$upgrade-dependencies +$review-pull-request #12 against @docs/features/reading-list/specification.md ``` -The session clarifies whether majors and toolchain changes are included, discovers outdated dependencies, checks compatibility and follows official upgrade guidance. It uses official CLI commands first, applies required migrations and verifies the local changes. The handoff reports version changes, validation, blockers and optional code improvements for the user to choose. It stops before publication, deployment or machine-wide changes unless separately authorised. - -### Debug - -#### `$debug` - -Enter here with observed and expected behaviour or another usable failure signal: +As Shelf grows, use the maintenance entry points for specific needs: ```text -$debug +$debug and fix Shelf adding the same book twice when I submit the form once ``` -The session establishes an evidence-backed root cause and stops there when diagnosis is the requested outcome. When repair is authorised, it produces a minimal, reviewed local change with regression evidence and stops before commit or publication. - ```text -$debug → $commit → $pull-request +$upgrade-dependencies in Shelf to the newest compatible stable versions ``` ## Supporting skills -These utilities and routers are independently invokable outside the main lifecycle path and may also be composed by lifecycle skills when their trigger applies. - -| Skill | Type | Invoke it to… | -| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `$review-pull-request` | Router | Independently assess someone else's pinned pull request without changing their branch or publishing a review unless requested | -| `$elicit` | Utility | Resolve material user-held information and decisions one question at a time | -| `$elicit-with-context` | Router | Resolve software-project questions through `$elicit`, always maintaining shared language and preserving qualifying decisions | -| `$research` | Utility | Investigate a material subject with high-trust evidence and persist a trusted cited report | -| `$maintain-agents` | Utility | Keep confirmed repository-wide agent guidance lean and current | +Lifecycle entry points invoke these focused capabilities when needed. You can also call them directly. -Use `$elicit-with-context` to work through questions or decisions within a software project. For non-software work, use `$elicit`. +| Skill | Purpose | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [$elicit](skills/elicit/SKILL.md) | Resolve material questions and decisions through a confirmed dialogue. | +| [$elicit-with-context](skills/elicit-with-context/SKILL.md) | Clarify a software task while maintaining project terminology and qualifying decision records. | +| [$research](skills/research/SKILL.md) | Produce a durable cited research report. | +| [$modular-design](skills/modular-design/SKILL.md) | Design simple interfaces that hide domain knowledge and complexity. | +| [$test-design](skills/test-design/SKILL.md) | Design minimal tests for observable behaviour. | +| [$measure-code-complexity](skills/measure-code-complexity/SKILL.md) | Measure code complexity and interpret signals that warrant attention. | +| [$code-cleanup](skills/code-cleanup/SKILL.md) | Independently identify deletions and simplifications that preserve behaviour. | +| [$code-review](skills/code-review/SKILL.md) | Independently assess code against requirements and engineering standards. | +| [$maintain-agents](skills/maintain-agents/SKILL.md) | Keep project instructions in `AGENTS.md` concise and current. | +| [$maintain-ubiquitous-language](skills/maintain-ubiquitous-language/SKILL.md) | Sharpen project terminology and maintain `GLOSSARY.md`. | +| [$maintain-decision-records](skills/maintain-decision-records/SKILL.md) | Preserve significant technical rationale and decision history. | +| [$write-prose](skills/write-prose/SKILL.md) | Write clear, succinct UK English. | +| [$write-skill](skills/write-skill/SKILL.md) | Create or refactor concise skills and verify their behaviour. | -## Acknowledgements +## Sources and acknowledgements -Propulsion is heavily inspired by other great skill sets: +Propulsion draws on these skill collections and resources: - [obra/superpowers](https://github.com/obra/superpowers) - [mattpocock/skills](https://github.com/mattpocock/skills) +- [PStack](https://github.com/cursor/plugins/tree/main/pstack) +- [Refactoring Guru](https://refactoring.guru/) diff --git a/bun.lock b/bun.lock index 8d0c7df..cf70be4 100644 --- a/bun.lock +++ b/bun.lock @@ -8,8 +8,12 @@ "oxfmt": "^0.59.0", "oxlint": "^1.74.0", "oxlint-tsgolint": "^0.24.0", - "semver": "7.8.5", - "tiktoken": "1.0.22", + }, + }, + "skills/write-skill": { + "name": "@propulsion/write-skill", + "dependencies": { + "js-tiktoken": "1.0.21", }, }, }, @@ -102,16 +106,18 @@ "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.74.0", "", { "os": "win32", "cpu": "x64" }, "sha512-VTC9IYTIMrVUk/i6Ms1ohzzDKZFkWn0KU2OBbPBzgmVZ2V30165T/zK4LztTr0Xgp9fZ1qQZ1rsZAu/rEmySlA=="], + "@propulsion/write-skill": ["@propulsion/write-skill@workspace:skills/write-skill"], + + "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="], + + "js-tiktoken": ["js-tiktoken@1.0.21", "", { "dependencies": { "base64-js": "^1.5.1" } }, "sha512-biOj/6M5qdgx5TKjDnFT1ymSpM5tbd3ylwDtrQvFQSu0Z7bBYko2dF+W/aUkXUPuk6IVpRxk/3Q2sHOzGlS36g=="], + "oxfmt": ["oxfmt@0.59.0", "", { "dependencies": { "tinypool": "2.1.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.59.0", "@oxfmt/binding-android-arm64": "0.59.0", "@oxfmt/binding-darwin-arm64": "0.59.0", "@oxfmt/binding-darwin-x64": "0.59.0", "@oxfmt/binding-freebsd-x64": "0.59.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.59.0", "@oxfmt/binding-linux-arm-musleabihf": "0.59.0", "@oxfmt/binding-linux-arm64-gnu": "0.59.0", "@oxfmt/binding-linux-arm64-musl": "0.59.0", "@oxfmt/binding-linux-ppc64-gnu": "0.59.0", "@oxfmt/binding-linux-riscv64-gnu": "0.59.0", "@oxfmt/binding-linux-riscv64-musl": "0.59.0", "@oxfmt/binding-linux-s390x-gnu": "0.59.0", "@oxfmt/binding-linux-x64-gnu": "0.59.0", "@oxfmt/binding-linux-x64-musl": "0.59.0", "@oxfmt/binding-openharmony-arm64": "0.59.0", "@oxfmt/binding-win32-arm64-msvc": "0.59.0", "@oxfmt/binding-win32-ia32-msvc": "0.59.0", "@oxfmt/binding-win32-x64-msvc": "0.59.0" }, "peerDependencies": { "svelte": "^5.0.0", "vite-plus": "*" }, "optionalPeers": ["svelte", "vite-plus"], "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-Xqk6cPZS1yMvVa7OAuenaDZUsgMDutvvbZ9/L5gSvAfW64+WN4HVhgipLj5rVERbYQt8fLs9TopyZ1rU1XEG/w=="], "oxlint": ["oxlint@1.74.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.74.0", "@oxlint/binding-android-arm64": "1.74.0", "@oxlint/binding-darwin-arm64": "1.74.0", "@oxlint/binding-darwin-x64": "1.74.0", "@oxlint/binding-freebsd-x64": "1.74.0", "@oxlint/binding-linux-arm-gnueabihf": "1.74.0", "@oxlint/binding-linux-arm-musleabihf": "1.74.0", "@oxlint/binding-linux-arm64-gnu": "1.74.0", "@oxlint/binding-linux-arm64-musl": "1.74.0", "@oxlint/binding-linux-ppc64-gnu": "1.74.0", "@oxlint/binding-linux-riscv64-gnu": "1.74.0", "@oxlint/binding-linux-riscv64-musl": "1.74.0", "@oxlint/binding-linux-s390x-gnu": "1.74.0", "@oxlint/binding-linux-x64-gnu": "1.74.0", "@oxlint/binding-linux-x64-musl": "1.74.0", "@oxlint/binding-openharmony-arm64": "1.74.0", "@oxlint/binding-win32-arm64-msvc": "1.74.0", "@oxlint/binding-win32-ia32-msvc": "1.74.0", "@oxlint/binding-win32-x64-msvc": "1.74.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.24.0", "vite-plus": "*" }, "optionalPeers": ["oxlint-tsgolint", "vite-plus"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-odGl2s2x5IOJoj3A0v1k0PGBXVFBZeZ2+AK/+K2MJur7Ghi3bkyX5NuLUWHKqa4js1wjep3hJeuTQJOlr+4+dA=="], "oxlint-tsgolint": ["oxlint-tsgolint@0.24.0", "", { "optionalDependencies": { "@oxlint-tsgolint/darwin-arm64": "0.24.0", "@oxlint-tsgolint/darwin-x64": "0.24.0", "@oxlint-tsgolint/linux-arm64": "0.24.0", "@oxlint-tsgolint/linux-x64": "0.24.0", "@oxlint-tsgolint/win32-arm64": "0.24.0", "@oxlint-tsgolint/win32-x64": "0.24.0" }, "bin": { "tsgolint": "bin/tsgolint.js" } }, "sha512-giCk5sEvG02d5tzPmFMX3hem8ndzEEu1xvGYS5OwNfO2WGl6ZVxt5LjE0yiMDoz94INI7XkXwgFAQiydPvVHDw=="], - "semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], - - "tiktoken": ["tiktoken@1.0.22", "", {}, "sha512-PKvy1rVF1RibfF3JlXBSP0Jrcw2uq3yXdgcEXtKTYn3QJ/cBRBHDnrJ5jHky+MENZ6DIPwNUGWpkVx+7joCpNA=="], - "tinypool": ["tinypool@2.1.0", "", {}, "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw=="], } } diff --git a/package.json b/package.json index 13a19a5..09b7c1b 100644 --- a/package.json +++ b/package.json @@ -1,19 +1,21 @@ { "name": "propulsion", "private": true, + "workspaces": [ + "skills/write-skill" + ], "scripts": { - "checks": "bun run lint && bun run format && bun run validate:skills", + "checks": "bun run lint && bun run format && bun run test && bun run validate:skills", "format": "oxfmt .", "format:check": "oxfmt --check .", "lint": "oxlint --no-error-on-unmatched-pattern", + "test": "bun test scripts", "validate:skills": "bun scripts/validate-skills.js" }, "devDependencies": { "oxfmt": "^0.59.0", "oxlint": "^1.74.0", - "oxlint-tsgolint": "^0.24.0", - "semver": "7.8.5", - "tiktoken": "1.0.22" + "oxlint-tsgolint": "^0.24.0" }, "packageManager": "bun@1.3.11" } diff --git a/scripts/count-tokens.test.js b/scripts/count-tokens.test.js new file mode 100644 index 0000000..eab9cef --- /dev/null +++ b/scripts/count-tokens.test.js @@ -0,0 +1,82 @@ +import { afterAll, expect, test } from 'bun:test'; +import { spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; + +const script = path.resolve('skills/write-skill/scripts/count-tokens.js'); +const workspace = mkdtempSync(path.join(tmpdir(), 'skill-tokens-')); +function run(args, input = '') { + return spawnSync(process.execPath, [script, ...args], { + input, + encoding: 'utf8', + timeout: 60000, + }); +} + +afterAll(() => rmSync(workspace, { recursive: true, force: true })); + +test('counts separate UTF-8 inputs and sums their tokens without changing files', () => { + const first = path.join(workspace, 'first.md'); + const second = path.join(workspace, 'second.md'); + writeFileSync(first, 'hello world'); + writeFileSync(second, 'こんにちは世界'); + const args = ['--encoding', 'o200k_base', first, second]; + const result = run(args); + expect(result.status).toBe(0); + expect(JSON.parse(result.stdout)).toEqual({ + encoding: 'o200k_base', + tokenizer: 'js-tiktoken', + tokenizer_version: '1.0.21', + inputs: [ + { input: first, tokens: 2 }, + { input: second, tokens: 2 }, + ], + total_tokens: 4, + }); + expect(run(args).stdout).toBe(result.stdout); + expect(readFileSync(second, 'utf8')).toBe('こんにちは世界'); +}); + +test('counts stdin, empty text, and literal special-token spellings', () => { + const empty = run(['--encoding', 'o200k_base']); + expect(JSON.parse(empty.stdout).total_tokens).toBe(0); + const literal = run(['--encoding', 'o200k_base', '-'], '<|endoftext|>'); + expect(literal.status).toBe(0); + expect(JSON.parse(literal.stdout).total_tokens).toBe(7); +}); + +test('uses the supplied encoding for the same text', () => { + const result = run(['--encoding', 'cl100k_base'], 'こんにちは世界'); + expect(result.status).toBe(0); + const report = JSON.parse(result.stdout); + expect(report.encoding).toBe('cl100k_base'); + expect(report.total_tokens).toBe(4); +}); + +test('reports encoding and input failures without partial output', () => { + const invalid = path.join(workspace, 'invalid.md'); + const valid = path.join(workspace, 'valid.md'); + writeFileSync(invalid, Buffer.from([0xff])); + writeFileSync(valid, 'hello world'); + for (const args of [ + ['--encoding', 'unknown'], + ['--encoding', 'o200k_base', path.join(workspace, 'missing.md')], + ['--encoding', 'o200k_base', invalid], + ['--encoding', 'o200k_base', valid, invalid], + ]) { + const result = run(args); + expect(result.status).toBe(1); + expect(result.stdout).toBe(''); + expect(JSON.parse(result.stderr).error.length).toBeGreaterThan(0); + } +}); + +test('requires an encoding and rejects repeated stdin inputs', () => { + for (const args of [[], ['--encoding', 'o200k_base', '-', '-']]) { + const result = run(args); + expect(result.status).toBe(2); + expect(result.stdout).toBe(''); + expect(JSON.parse(result.stderr).error.length).toBeGreaterThan(0); + } +}); diff --git a/scripts/measure-code-complexity.test.js b/scripts/measure-code-complexity.test.js new file mode 100644 index 0000000..dd7b0d2 --- /dev/null +++ b/scripts/measure-code-complexity.test.js @@ -0,0 +1,426 @@ +import { afterEach, expect, test } from 'bun:test'; +import { + chmodSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + symlinkSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; + +const helper = resolve('skills/measure-code-complexity/scripts/measure.py'); +const scratch = []; +const run = (command, cwd, environment = {}) => { + const result = Bun.spawnSync(command, { + cwd, + env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1', ...environment }, + }); + return { + code: result.exitCode, + text: result.stdout.toString(), + error: result.stderr.toString(), + }; +}; +const bundleModule = resolve('skills/measure-code-complexity/scripts'); +const bundled = run([ + 'python3', + '-c', + `import sys; sys.path.insert(0, ${JSON.stringify(bundleModule)}); from bundled_cccc import executable; print(executable())`, +]).text.trim(); +function write(directory, name, content) { + const path = join(directory, name); + mkdirSync(resolve(path, '..'), { recursive: true }); + writeFileSync(path, content); + return path; +} +function repository() { + const directory = mkdtempSync(join(tmpdir(), 'complexity-test-')); + scratch.push(directory); + for (const args of [ + ['init', '-q'], + ['config', 'user.name', 'Fixture'], + ['config', 'user.email', 'fixture@example.invalid'], + ]) { + expect(run(['git', ...args], directory).code).toBe(0); + } + write( + directory, + 'price.py', + 'def price(value):\n if value < 0:\n return 0\n return value\n\ndef unchanged(value):\n return value * 2\n', + ); + expect(run(['git', 'add', '.'], directory).code).toBe(0); + expect(run(['git', 'commit', '-qm', 'fixture'], directory).code).toBe(0); + return directory; +} +function measure(directory, ...args) { + const result = run( + ['python3', helper, '--repo', directory, ...args], + directory, + ); + const json = JSON.parse(result.text); + let report; + if (json.report) { + scratch.push(json.report); + report = JSON.parse(readFileSync(json.report, 'utf8')); + } + return { ...result, json, report }; +} +function flatten(functions) { + return functions.flatMap((f) => [f, ...flatten(f.children ?? [])]); +} +function fakeTool(directory, code) { + const path = write( + directory, + 'fake-cccc', + `#!/usr/bin/env python3\nimport sys, json, subprocess\nif '--version' in sys.argv:\n print('cccc fixture')\nelse:\n${code}\n`, + ); + chmodSync(path, 0o755); + return path; +} +afterEach(() => { + for (const path of scratch.splice(0)) + rmSync(path, { recursive: true, force: true }); +}); + +test('measures every function in changed production files and saves deterministic cccc-shaped JSON without project edits', () => { + const directory = repository(); + write( + directory, + 'price.py', + 'def price(value):\n return value\n\ndef unchanged(value):\n return value * 2\n', + ); + write( + directory, + 'new.ts', + 'export const discount = (value: number) => value / 2;\n', + ); + write(directory, 'new.test.ts', 'function testDiscount() {}\n'); + write(directory, 'tests/check.py', 'def check():\n assert True\n'); + write(directory, 'generated/ignored.ts', 'function generated() {}\n'); + write(directory, 'settings.json', '{"currency":"GBP"}'); + const before = run(['git', 'status', '--porcelain'], directory).text; + const result = measure(directory); + expect(result.code).toBe(0); + expect(result.json.status).toBe('complete'); + expect(result.json.schema).toBe(4); + expect(result.json).not.toHaveProperty('files'); + expect(result.json).not.toHaveProperty('functions'); + expect(result.report.scope.files).toEqual(['new.ts', 'price.py']); + expect( + result.report.files.flatMap((f) => + flatten(f.functions).map((fn) => fn.name), + ), + ).toEqual(['discount', 'price', 'unchanged']); + expect(result.report.scope.excluded_files).toContain('tests/check.py'); + const price = result.report.files.find((f) => f.path === 'price.py') + .functions[0]; + expect(price.cyclomatic).toBe(1); + expect(price.lizard.nloc).toBe(2); + expect(price.lizard).not.toHaveProperty('cyclomatic'); + expect(result.report).not.toHaveProperty('baseFunctions'); + expect(result.report.summary).not.toHaveProperty('loc'); + expect(JSON.stringify(result.report)).not.toContain('tokenCount'); + expect(JSON.stringify(result.report)).not.toContain('baseline'); + expect(result.report.scope.content_id).toMatch(/^[a-f0-9]{64}$/); + expect(result.report).toEqual(measure(directory).report); + expect(run(['git', 'status', '--porcelain'], directory).text).toBe(before); + expect(result.json.report.startsWith(directory)).toBe(false); + const native = JSON.parse( + run( + [ + bundled, + '--no-config', + '--no-cache', + join(directory, 'new.ts'), + join(directory, 'price.py'), + ], + directory, + ).text, + ); + expect(result.report.summary.cognitive).toEqual(native.summary.cognitive); + expect(result.report.summary.cyclomatic).toEqual(native.summary.cyclomatic); +}); + +test('uses a base only for file selection and explicit files for repeated caller-owned measurements', () => { + const directory = repository(); + const base = run(['git', 'rev-parse', 'HEAD'], directory).text.trim(); + write(directory, 'new.py', 'def new(value):\n return value + 1\n'); + expect(run(['git', 'add', '.'], directory).code).toBe(0); + expect(run(['git', 'commit', '-qm', 'addition'], directory).code).toBe(0); + expect(measure(directory).report.files).toEqual([]); + const selected = measure(directory, '--base', base); + expect(selected.report.scope.files).toEqual(['new.py']); + expect(selected.report.scope.selection_base).toBe(base); + expect(selected.report.files[0].functions[0].cyclomatic).toBe(1); + const before = measure(directory, 'price.py'); + write(directory, 'price.py', 'def price(value):\n return value\n'); + const after = measure(directory, 'price.py'); + expect(after.report.scope.content_id).not.toBe( + before.report.scope.content_id, + ); + expect(after.report.summary.cyclomatic.max).toBe(1); + expect(after.report.summary).not.toHaveProperty('delta'); +}); + +test('counts nested functions once per tool and verifies the cognitive guard-clause example with real parsers', () => { + const directory = repository(); + write( + directory, + 'nested.py', + 'def outer(value):\n def inner():\n if value:\n return value\n return 0\n return inner()\n', + ); + write( + directory, + 'before.ts', + 'function offer(active: boolean, held: boolean) {\n if (active) {\n if (held) return "held";\n return "offer";\n }\n return "inactive";\n}\n', + ); + write( + directory, + 'after.ts', + 'function offer(active: boolean, held: boolean) {\n if (!active) return "inactive";\n if (held) return "held";\n return "offer";\n}\n', + ); + const result = measure(directory, 'nested.py', 'before.ts', 'after.ts'); + expect(result.json.status).toBe('complete'); + const byPath = Object.fromEntries( + result.report.files.map((f) => [f.path, f]), + ); + expect(byPath['before.ts'].functions[0].cyclomatic).toBe(3); + expect(byPath['after.ts'].functions[0].cyclomatic).toBe(3); + expect(byPath['before.ts'].functions[0].cognitive).toBe(3); + expect(byPath['after.ts'].functions[0].cognitive).toBe(2); + const outer = byPath['nested.py'].functions[0]; + expect(outer.lizard.max_nesting).toBe(0); + expect(outer.children[0].lizard.max_nesting).toBe(1); + expect(result.report.summary.function_count).toBe(4); + expect(result.report.summary.lizard.function_count).toBe(4); + expect(result.report.summary.lizard.attached_function_count).toBe(4); +}); + +test('reports all attention signals and clone locations with advisory thresholds, while high scores still succeed', () => { + const directory = repository(); + const branches = Array.from( + { length: 9 }, + (_, i) => ` if value == ${i}:\n return ${i}\n`, + ).join(''); + write(directory, 'flat.py', `def flat(value):\n${branches} return -1\n`); + write( + directory, + 'deep.py', + 'def deep(a, b, c, d, e, f):\n if a:\n if b:\n if c:\n if d:\n if e:\n if f:\n return 1\n return 0\n', + ); + write( + directory, + 'large.py', + `def large(value):\n${Array.from({ length: 65 }, (_, i) => ` item${i} = value + ${i}\n`).join('')} return value\n`, + ); + const clone = `def calculate(value):\n${Array.from({ length: 80 }, (_, i) => ` value += ${i}\n`).join('')} return value\n`; + write(directory, 'clone-a.py', clone); + write(directory, 'clone-b.py', clone); + const result = measure(directory); + expect(result.code).toBe(0); + expect(result.json.status).toBe('complete'); + for (const [key, minimum] of Object.entries({ + cyclomatic: 10, + cognitive: 16, + nloc: 61, + max_nesting: 4, + parameters: 6, + })) { + expect(result.json.summary.attention[key].minimum).toBe(minimum); + expect(result.json.summary.attention[key].count).toBeGreaterThan(0); + } + expect( + result.report.files.find((f) => f.path === 'flat.py').functions[0] + .cyclomatic, + ).toBe(10); + expect( + result.report.files.find((f) => f.path === 'deep.py').functions[0] + .cognitive, + ).toBe(21); + expect( + result.report.files.find((f) => f.path === 'deep.py').functions[0] + .lizard.max_nesting, + ).toBe(6); + expect(result.json.summary.lizard.duplication.minimum_tokens).toBe(70); + expect(result.json.summary.attention.duplication.count).toBeGreaterThan(0); + expect( + result.report.duplicates.flatMap((g) => g.locations.map((p) => p.path)), + ).toContain('clone-a.py'); + expect( + result.report.duplicates.flatMap((g) => g.locations.map((p) => p.path)), + ).toContain('clone-b.py'); + expect(result.json.summary.lizard.duplication.rate).toBeGreaterThan(0); + expect(result.json.summary.lizard.duplication.rate).toBeLessThanOrEqual(1); +}); + +test('surfaces unsupported sources and partial parses rather than declaring zero complexity complete', () => { + const directory = repository(); + write(directory, 'unknown.xyz', 'unsupported production language'); + write(directory, 'broken.ts', 'export function broken( {\n'); + const result = measure(directory, 'unknown.xyz', 'broken.ts'); + expect(result.code).toBe(0); + expect(result.json.status).toBe('partial'); + expect(result.json.limitation_count).toBeGreaterThan(0); + expect(result.report.limitations).toContainEqual({ + path: 'unknown.xyz', + tool: 'cccc', + reason: 'source not reported', + }); + expect(result.report.summary.parse_error_count).toBeGreaterThan(0); + expect( + result.report.files.find((f) => f.path === 'broken.ts').parse_errors + .length, + ).toBeGreaterThan(0); + expect(result.report).not.toHaveProperty('crap'); + expect(result.report).not.toHaveProperty('coverage'); +}); + +test('keeps ambiguous matches separate instead of attaching a supporting score to the wrong function', () => { + const directory = repository(); + const executable = fakeTool( + directory, + ` report = {"files": [{"path": sys.argv[-1], "cognitive": 0, "cyclomatic": 2, "functions": [{"name": "price", "line": 1, "kind": "function", "cognitive": 0, "cyclomatic": 1}, {"name": "price", "line": 1, "kind": "function", "cognitive": 0, "cyclomatic": 1}]}], "summary": {"file_count": 1, "function_count": 2, "parse_error_count": 0, "parse_error_file_count": 0, "cognitive": {"sum": 0, "max": 0, "median": 0, "p90": 0, "p95": 0}, "cyclomatic": {"sum": 2, "max": 1, "median": 1, "p90": 1, "p95": 1}}}\n print(json.dumps(report))`, + ); + const result = measure(directory, '--cccc', executable, 'price.py'); + expect(result.json.status).toBe('partial'); + expect(result.report.files[0].functions[0]).not.toHaveProperty('lizard'); + expect(result.report.files[0].lizard_unmatched[0].name).toBe('price'); + expect(result.report.summary.lizard.attached_function_count).toBe(0); + expect(result.report.summary.cyclomatic.max).toBe(1); +}); + +test('rejects missing tools, invalid reports, paths outside scope and obsolete arguments', () => { + const directory = repository(); + expect(measure(directory, '--base', 'missing-revision').code).toBe(2); + expect(measure(directory, 'missing.py').code).toBe(2); + const outside = repository(); + expect(measure(directory, join(outside, 'price.py')).code).toBe(2); + symlinkSync(join(outside, 'price.py'), join(directory, 'escaped.py')); + expect(measure(directory, 'escaped.py').code).toBe(2); + expect( + measure(directory, '--cccc', '/missing/cccc', 'price.py').json.status, + ).toBe('failed'); + const invalid = fakeTool(directory, ' print("[]")'); + const failed = measure(directory, '--cccc', invalid, 'price.py'); + expect(failed.code).toBe(2); + expect(failed.json.error).toContain('unsupported report shape'); + for (const option of [ + '--all', + '--whole-repository', + '--fingerprint', + '--coverage', + '--duplicate-tokens', + ]) { + const result = run( + ['python3', helper, '--repo', directory, option], + directory, + ); + expect(result.code).toBe(2); + expect(result.error).toContain('unrecognized arguments'); + } +}); + +test('detects source changes during a run and emits no usable stale report', () => { + const directory = repository(); + const executable = fakeTool( + directory, + ` result = subprocess.run([${JSON.stringify(bundled)}, *sys.argv[1:]], capture_output=True, text=True, check=True)\n with open(sys.argv[-1], 'a') as stream: stream.write('\\n# changed during measurement\\n')\n print(result.stdout)`, + ); + const result = measure(directory, '--cccc', executable, 'price.py'); + expect(result.code).toBe(2); + expect(result.json.status).toBe('failed'); + expect(result.json.error).toContain('changed during measurement'); + expect(result.json).not.toHaveProperty('report'); +}); + +test('runs without a separately installed complexity executable and reuses verified bundled extraction', () => { + const directory = repository(); + const bin = join(directory, 'bin'); + mkdirSync(bin); + for (const command of ['python3', 'git']) + symlinkSync(Bun.which(command), join(bin, command)); + const environment = { PATH: bin }; + const absent = run( + ['python3', '-c', 'import shutil; print(shutil.which("cccc"))'], + directory, + environment, + ); + expect(absent.text.trim()).toBe('None'); + const before = run(['git', 'status', '--porcelain'], directory).text; + const measured = run( + ['python3', helper, '--repo', directory, 'price.py'], + directory, + environment, + ); + const result = JSON.parse(measured.text); + if (result.report) scratch.push(result.report); + expect(measured.code).toBe(0); + expect(result.status).toBe('complete'); + expect(result.tools.cccc).toBe('cccc 1.7.0'); + expect(result.summary.function_count).toBe(2); + expect(run(['git', 'status', '--porcelain'], directory).text).toBe(before); + expect( + run([bundled, '--version'], directory, environment).text.trim(), + ).toBe('cccc 1.7.0'); +}); + +test('selects all five published platform archives and verifies every packaged executable', () => { + const result = run([ + 'python3', + '-c', + `import sys, json, hashlib, tarfile, zipfile +sys.path.insert(0, ${JSON.stringify(bundleModule)}) +import bundled_cccc as b +hosts=[('Darwin','arm64'),('Darwin','x86_64'),('Linux','aarch64'),('Linux','AMD64'),('Windows','AMD64')] +manifest=json.loads((b.BUNDLE/'manifest.json').read_text())['targets'] +for host in hosts: + spec=manifest[b.target(*host)]; archive=b.BUNDLE/spec['archive'] + assert hashlib.sha256(archive.read_bytes()).hexdigest()==spec['archive_sha256'] + if archive.suffix=='.zip': + with zipfile.ZipFile(archive) as z: data=z.read(spec['member']) + else: + with tarfile.open(archive) as z: data=z.extractfile(spec['member']).read() + assert hashlib.sha256(data).hexdigest()==spec['binary_sha256'] + assert data[:4] in [b'\\xcf\\xfa\\xed\\xfe', b'\\x7fELF'] or data[:2]==b'MZ' + print(b.target(*host)) +try: b.target('Windows','ARM64') +except ValueError as e: print(e) +else: raise AssertionError('unsupported target accepted')`, + ]); + expect(result.code).toBe(0); + expect(result.text.trim().split('\n')).toHaveLength(6); + expect(result.text).toContain('No bundled binary for Windows arm64'); +}); + +test('rejects modified archives and cached executables before running them', () => { + const directory = mkdtempSync(join(tmpdir(), 'complexity-bundle-test-')); + scratch.push(directory); + const result = run([ + 'python3', + '-c', + `import sys, json, hashlib +from pathlib import Path +sys.path.insert(0, ${JSON.stringify(bundleModule)}) +import bundled_cccc as b +root=Path(${JSON.stringify(directory)}); b.BUNDLE=root; b.tempfile.tempdir=str(root) +archive=root/'modified.tar.gz'; archive.write_bytes(b'changed') +spec={'archive':archive.name,'archive_sha256':hashlib.sha256(b'original').hexdigest(),'member':'cccc','binary_sha256':hashlib.sha256(b'original binary').hexdigest()} +(root/'manifest.json').write_text(json.dumps({'targets':{b.target():spec}})) +try: b.executable() +except ValueError as e: print(e) +else: raise AssertionError('modified archive accepted') +spec['archive_sha256']=hashlib.sha256(archive.read_bytes()).hexdigest() +(root/'manifest.json').write_text(json.dumps({'targets':{b.target():spec}})) +cache=root/('propulsion-cccc-'+str(b.os.getuid())); cache.mkdir() +(cache/spec['binary_sha256']).write_bytes(b'modified executable') +try: b.executable() +except ValueError as e: print(e) +else: raise AssertionError('modified executable accepted')`, + ]); + expect(result.code).toBe(0); + expect(result.text).toContain('Bundled archive checksum mismatch'); + expect(result.text).toContain('Cached executable checksum mismatch'); +}); diff --git a/scripts/validate-skill.test.js b/scripts/validate-skill.test.js new file mode 100644 index 0000000..b4e421c --- /dev/null +++ b/scripts/validate-skill.test.js @@ -0,0 +1,284 @@ +import { afterEach, expect, test } from 'bun:test'; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; + +import { validateSkill } from '../skills/write-skill/scripts/validate-skill.js'; +import { validateSkills } from './validate-skills.js'; + +const workspaces = []; + +afterEach(() => { + for (const workspace of workspaces.splice(0)) + rmSync(workspace, { recursive: true, force: true }); +}); + +function fixture( + frontmatter = 'name: sample-skill\ndescription: Handle a specific recurring task.', + body = 'Perform the requested task.', +) { + const workspace = mkdtempSync(path.join(tmpdir(), 'skill-validation-')); + workspaces.push(workspace); + const root = path.join(workspace, 'sample-skill'); + mkdirSync(root); + writeFileSync( + path.join(root, 'SKILL.md'), + `---\n${frontmatter}\n---\n\n${body}\n`, + ); + mkdirSync(path.join(root, 'agents')); + writeFileSync( + path.join(root, 'agents/openai.yaml'), + 'interface:\n display_name: "Sample Skill"\n short_description: "Handle a specific recurring task"\n', + ); + return root; +} + +test('accepts flexible descriptions and layouts with the required OpenAI adapter', () => { + const root = fixture( + 'name: sample-skill\ndescription: >-\n Handle the task\n when its condition applies.', + 'Read the input.\n\nReturn the checked result.', + ); + expect(validateSkill(root).valid).toBe(true); +}); + +test('requires the OpenAI adapter and reports its malformed YAML', () => { + const root = fixture(); + const adapter = path.join(root, 'agents/openai.yaml'); + rmSync(adapter); + expect(validateSkill(root).errors[0]).toContain('agents/openai.yaml'); + writeFileSync(adapter, 'interface: ['); + expect(validateSkill(root).valid).toBe(false); + writeFileSync(adapter, '- not-a-mapping'); + expect(validateSkill(root).errors).toEqual([ + 'agents/openai.yaml: must be a YAML mapping.', + ]); +}); + +test('requires OpenAI UI metadata', () => { + const root = fixture(); + const adapter = path.join(root, 'agents/openai.yaml'); + writeFileSync(adapter, 'interface: {}'); + expect(validateSkill(root).errors).toHaveLength(2); + writeFileSync( + adapter, + 'interface:\n display_name: 7\n short_description: " "', + ); + expect(validateSkill(root).errors).toHaveLength(2); + writeFileSync(adapter, 'interface: []'); + expect(validateSkill(root).errors).toHaveLength(1); +}); + +test('enforces naming and description limits', () => { + const root = fixture(`name: Wrong--Name\ndescription: ${'x'.repeat(1025)}`); + expect(validateSkill(root).errors).toHaveLength(2); +}); + +test('reports a directory-name mismatch', () => { + const root = fixture('name: other-skill\ndescription: Do the task.'); + expect(validateSkill(root).errors).toEqual([ + 'name must match the skill directory name.', + ]); +}); + +test('reports malformed YAML and missing skill files', () => { + const root = fixture('name: ['); + const invalid = validateSkill(root); + expect(invalid.valid).toBe(false); + expect(invalid.tokens.root_tokens).toBeGreaterThan(0); + rmSync(path.join(root, 'SKILL.md')); + expect(validateSkill(root).valid).toBe(false); +}); + +test('checks inline and reference links while ignoring literal examples', () => { + const root = fixture( + undefined, + '[Present](references/present.md#section)\n[Missing][missing]\n\n[missing]: references/absent.md\n\n```markdown\n[Illustration](not-a-real-file.md)\n```\n\n`[Literal](also-not-real.md)`', + ); + mkdirSync(path.join(root, 'references')); + writeFileSync( + path.join(root, 'references/present.md'), + '# Section\n\nContent.', + ); + const result = validateSkill(root); + expect(result.errors).toHaveLength(1); + expect(result.errors[0]).toContain('references/absent.md'); +}); + +test('checks links relative to reference files, including spaces and parentheses', () => { + const root = fixture(undefined, '[Details](references/details.md)'); + mkdirSync(path.join(root, 'references')); + writeFileSync( + path.join(root, 'references/details.md'), + '[File](<../a file.md>)\n[Other](../result(v1).md)\n[Remote](https://example.com)', + ); + writeFileSync(path.join(root, 'a file.md'), 'Content.'); + writeFileSync(path.join(root, 'result(v1).md'), 'Content.'); + expect(validateSkill(root).valid).toBe(true); +}); + +test('does not interpret YAML or escaped link syntax as Markdown links', () => { + const root = fixture( + 'name: sample-skill\ndescription: Explain [example](not-a-resource.md) when useful.', + '\\[Literal](absent.md)\n', + ); + expect(validateSkill(root).valid).toBe(true); +}); + +test('recognises nested parentheses and parenthesised link titles', () => { + const root = fixture( + undefined, + '[Nested](absent(v1(extra)).md)\n[Title](missing.md (A title))', + ); + const result = validateSkill(root); + expect(result.errors).toHaveLength(2); + expect(result.errors[0]).toContain('absent(v1(extra)).md'); + expect(result.errors[1]).toContain('missing.md'); +}); + +test('default headings and a completion gate pass without warnings', () => { + const root = fixture( + undefined, + '# Sample\n\nProduce a result.\n\n## Inputs ##\n\nUse supplied data.\n\n## Method\n\n```sh\nrun-task\n```\n\n## Finish\n\nReturn the result.\n\n**Done only when** all rows are checked.', + ); + expect(validateSkill(root).warnings).toEqual([]); + writeFileSync( + path.join(root, 'SKILL.md'), + '---\nname: sample-skill\ndescription: Do a task.\n---\n\nInputs\n------\nUse data.\n\nMethod\n------\nCheck data.\n\nFinish\n------\nFinish when all rows are checked.', + ); + expect(validateSkill(root).warnings).toEqual([]); +}); + +test('tiny layouts stay valid and expose advisory warnings in CLI and summary output', () => { + const root = fixture( + undefined, + '# Sample\n\nUse guard clauses. Stop when behaviour is unchanged.', + ); + const result = validateSkill(root); + expect(result.valid).toBe(true); + expect(result.warnings).toHaveLength(1); + expect(result.warnings[0]).toContain( + 'missing default headings: Inputs, Method, Finish', + ); + const validator = new URL( + '../skills/write-skill/scripts/validate-skill.js', + import.meta.url, + ).pathname; + const cli = Bun.spawnSync([process.execPath, validator, root]); + expect(cli.exitCode).toBe(0); + expect(JSON.parse(cli.stdout.toString()).warnings).toEqual(result.warnings); + const summary = validateSkills(path.dirname(root)); + expect(summary.valid).toBe(true); + expect(summary.failures).toEqual([]); + expect(summary.warnings).toEqual([ + { skill: 'sample-skill', warnings: result.warnings }, + ]); +}); + +test('warns about misordered and empty sections without blocking packaging', () => { + const root = fixture( + undefined, + '## Method\n\n\n\n## Inputs\n\n## Finish\n\nReturn the report. Done only when every row is checked.', + ); + const result = validateSkill(root); + expect(result.valid).toBe(true); + expect(result.warnings).toHaveLength(3); + expect(result.warnings[0]).toContain('out of order'); + expect(result.warnings[1]).toContain('Inputs section is empty'); + expect(result.warnings[2]).toContain('Method section is empty'); +}); + +test('root layout warnings ignore frontmatter, literal examples, comments, and references', () => { + const root = fixture( + 'name: sample-skill\ndescription: Finish when a task is complete.', + '```markdown\n## Inputs\n## Method\n## Finish\nDone only when every row is checked.\n```\n\n`Finish when ready.`\n\n[Details](references/details.md)', + ); + mkdirSync(path.join(root, 'references')); + writeFileSync( + path.join(root, 'references/details.md'), + '## Inputs\nData\n## Method\nCheck\n## Finish\nDone only when every row is checked.', + ); + const result = validateSkill(root); + expect(result.valid).toBe(true); + expect(result.warnings).toHaveLength(2); + expect(result.warnings[0]).toContain('missing default headings'); + expect(result.warnings[1]).toContain('no recognisable completion gate'); +}); + +test('rejects absolute local links while preserving relative and remote links', () => { + const root = fixture(); + const existing = path.join(root, 'details.md'); + writeFileSync(existing, 'Details.'); + writeFileSync( + path.join(root, 'SKILL.md'), + `---\nname: sample-skill\ndescription: Do a task.\n---\n\n[Absolute](${existing})\n[Encoded](${encodeURIComponent(existing)})\n[Windows](C:/skills/details.md)\n[File URL](file://${existing})\n[Relative](details.md)\n[Remote](https://example.com)\n[Protocol-relative](//example.com/details.md)\n`, + ); + const result = validateSkill(root); + expect(result.valid).toBe(false); + expect(result.errors).toHaveLength(4); + expect( + result.errors.every((error) => error.includes('absolute local path')), + ).toBe(true); +}); + +test('reports root and stored Markdown counts separately', () => { + const root = fixture(); + mkdirSync(path.join(root, 'references')); + mkdirSync(path.join(root, 'assets')); + writeFileSync(path.join(root, 'references/details.md'), 'hello world'); + writeFileSync(path.join(root, 'assets/example.md'), 'こんにちは世界'); + const result = validateSkill(root); + expect(result.valid).toBe(true); + expect(result.tokens).toMatchObject({ + encoding: 'o200k_base', + tokenizer: 'js-tiktoken', + tokenizer_version: '1.0.21', + }); + expect(result.tokens.files.slice(1)).toEqual([ + { file: 'assets/example.md', tokens: 2 }, + { file: 'references/details.md', tokens: 2 }, + ]); + expect(result.tokens.root_tokens).toBe(21); + expect(result.tokens.markdown_tokens).toBe(25); +}); + +test('all-skills summary retains counts and reports failures while checking every bundle', () => { + const root = fixture(); + const parent = path.dirname(root); + mkdirSync(path.join(parent, 'broken-skill')); + const result = validateSkills(parent); + expect(result.checked).toBe(2); + expect(result.valid).toBe(false); + expect(result.tokens.skills.map((skill) => skill.skill)).toEqual([ + 'broken-skill', + 'sample-skill', + ]); + expect(result.tokens.skills[1].root_tokens).toBeGreaterThan(0); + expect(result.failures).toHaveLength(1); + expect(result.failures[0].skill).toBe('broken-skill'); + expect( + result.failures[0].errors.every((error) => error.includes('ENOENT')), + ).toBe(true); + rmSync(path.join(parent, 'broken-skill'), { recursive: true }); + expect(validateSkills(parent)).toMatchObject({ + checked: 1, + valid: true, + failures: [], + }); +}); + +test('CLI emits valid JSON and distinct validity and usage exits', () => { + const root = fixture(); + const validator = new URL( + '../skills/write-skill/scripts/validate-skill.js', + import.meta.url, + ).pathname; + const valid = Bun.spawnSync([process.execPath, validator, root]); + expect(valid.exitCode).toBe(0); + expect(JSON.parse(valid.stdout.toString()).valid).toBe(true); + rmSync(path.join(root, 'SKILL.md')); + const invalid = Bun.spawnSync([process.execPath, validator, root]); + expect(invalid.exitCode).toBe(1); + expect(JSON.parse(invalid.stdout.toString()).valid).toBe(false); + const usage = Bun.spawnSync([process.execPath, validator]); + expect(usage.exitCode).toBe(2); +}); diff --git a/scripts/validate-skills.js b/scripts/validate-skills.js index de37439..db88064 100644 --- a/scripts/validate-skills.js +++ b/scripts/validate-skills.js @@ -1,30 +1,48 @@ #!/usr/bin/env bun -import { spawnSync } from 'node:child_process'; import { readdirSync } from 'node:fs'; +import path from 'node:path'; import { fileURLToPath } from 'node:url'; -const skillRoot = fileURLToPath(new URL('../skills/', import.meta.url)); -const validator = fileURLToPath( - new URL('../skills/write-skill/scripts/validate-skill.js', import.meta.url), -); -const skillDirectories = readdirSync(skillRoot, { withFileTypes: true }) - .filter((entry) => entry.isDirectory()) - .map((entry) => - fileURLToPath( - new URL(`${entry.name}/`, new URL('../skills/', import.meta.url)), - ), - ) - .toSorted(); - -let valid = true; +import { tokenMetadata } from '../skills/write-skill/scripts/count-tokens.js'; +import { validateSkill } from '../skills/write-skill/scripts/validate-skill.js'; -for (const skillDirectory of skillDirectories) { - const result = spawnSync(process.execPath, [validator, skillDirectory], { - stdio: 'inherit', - }); +const skillRoot = fileURLToPath(new URL('../skills/', import.meta.url)); - if (result.status !== 0) valid = false; +export function validateSkills(directory = skillRoot) { + const results = readdirSync(directory, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => path.join(directory, entry.name)) + .toSorted() + .map(validateSkill); + return { + checked: results.length, + valid: results.every((result) => result.valid), + tokens: { + ...tokenMetadata, + skills: results.map((result) => ({ + skill: path.basename(result.skill), + root_tokens: result.tokens.root_tokens, + markdown_tokens: result.tokens.markdown_tokens, + })), + }, + failures: results + .filter((result) => !result.valid) + .map((result) => ({ + skill: path.basename(result.skill), + errors: result.errors, + })), + warnings: results + .filter((result) => result.warnings.length) + .map((result) => ({ + skill: path.basename(result.skill), + warnings: result.warnings, + })), + }; } -process.exitCode = valid ? 0 : 1; +if (import.meta.main) { + const result = validateSkills(); + console.log(JSON.stringify(result)); + process.exitCode = result.valid ? 0 : 1; +} diff --git a/skills/code-cleanup/SKILL.md b/skills/code-cleanup/SKILL.md new file mode 100644 index 0000000..3f0cb30 --- /dev/null +++ b/skills/code-cleanup/SKILL.md @@ -0,0 +1,24 @@ +--- +name: code-cleanup +description: Identify behaviour-preserving deletions and simplifications when a file, branch diff, capability or codebase needs independent cleanup review. +--- + +# Code cleanup + +Find the least code that preserves supported behaviour. **Subtract before adding**. A fresh agent owns the read-only review. The caller owns decisions, edits and verification. + +## Inputs + +Take the cleanup scope from the request. Accept a file, diff, capability or whole codebase. Follow related files across the whole affected capability, including unchanged code. Keep unrelated work outside scope. Resolve an unclear scope before dispatch. + +## Method + +1. **Fix the packet.** Record the candidate revision or working-tree contents, comparison base when relevant, scope and source paths. Include requirements and repository instructions. Exclude implementation history, author rationale, suggested findings and prior review conclusions. +2. **Dispatch fresh.** Give that packet and [review instructions](references/review.md) to a fresh agent with no conversation history. Only the reviewer loads the technique references and report template. If already dispatched as that reviewer, follow the review instructions directly without spawning another agent. +3. **Check the handoff.** Verify the returned report exists, identifies the supplied candidate and accounts for scope. Return missing coverage to the reviewer. A changed candidate requires a refreshed review. + +## Finish + +Return only the absolute path to the saved report. If no report could be written, return the exact blocker instead of a path. Leave report reading and candidate adjudication to the caller. Resolve preservation gaps before applying a transformation. + +**Done only when** the fresh review accounts for the whole scope, completes its final coverage pass and saves a verified report of supported or explicitly uncertain candidates, or `No findings.`. An incomplete review must identify uninspected scope and cannot claim a clean result. diff --git a/skills/code-cleanup/agents/openai.yaml b/skills/code-cleanup/agents/openai.yaml new file mode 100644 index 0000000..1f3faf8 --- /dev/null +++ b/skills/code-cleanup/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: 'Code Cleanup' + short_description: 'Find deletions and simplifications through fresh review' diff --git a/skills/code-cleanup/assets/cleanup-report.md b/skills/code-cleanup/assets/cleanup-report.md new file mode 100644 index 0000000..7ad7367 --- /dev/null +++ b/skills/code-cleanup/assets/cleanup-report.md @@ -0,0 +1,41 @@ +# Cleanup review + +## Scope and status + +- Repository: {absolute path} +- Candidate: {revision or compact working-tree digest, comparison base when relevant} +- Requested scope: {file, diff, capability or codebase} +- Expanded capability: {related files and why they belong} +- Status: {Complete or Incomplete, with exact missing inspection} +- Behavioural authorities: {requirements and contract paths} + +## Candidate index + +| ID | Priority | Candidate and location | Technique | Preservation evidence or gap | +| --- | --------------------- | ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------------- | +| C1 | {High, Medium or Low} | {short title, repository-relative file and line or symbol} | {named transformation} | {Supported and key evidence, or Needs evidence and exact gap} | + +Replace the table with `No findings.` if a complete review found no justified candidate. For an incomplete review with none found, say `No candidates identified in the inspected portion.` + +## Candidate details + +### C1. {Concise transformation title} + +- Locations: {verified absolute paths and lines or symbols, including related unchanged files} +- Burden: {unnecessary machinery and its concrete maintenance consequence} +- Transformation: {technique and complete proposed edits, caller migration and orphan deletion} +- Preservation: {Supported or Needs evidence, traced behaviour and consumers, contrary evidence and exact remaining gap} +- Verification: {existing checks or focused comparison the caller should run, including how to resolve the gap} + +Use a short before/after sketch only when it clarifies a structural change. Give enough detail to implement the transformation without producing a speculative patch. Repeat this block for every indexed candidate, without repeating the index verbatim. Omit this section when there are no candidates. + +## Coverage and limitations + +- Inspected: {files or compact complete inventory, entry points, consumers and implicit-use checks} +- Families considered: {relevant technique families and material exclusions} +- Evidence used: {supplied checks and source reasoning} +- Probes run: {actual invocation and outcome, or None} +- Final coverage pass: {missed-candidate and orphan checks, candidate freshness} +- Limitations: {uninspected scope, missing authority and concrete out-of-scope issues, or None} + +Keep candidate-specific gaps in their preservation fields. State limitations here only when they affect the review as a whole. diff --git a/skills/code-cleanup/references/boundaries-and-protection.md b/skills/code-cleanup/references/boundaries-and-protection.md new file mode 100644 index 0000000..eec3459 --- /dev/null +++ b/skills/code-cleanup/references/boundaries-and-protection.md @@ -0,0 +1,96 @@ +# Boundaries and protection + +Read when redundant validation, error handling, comments or test scaffolding may be removable. + +## Delete a proven redundant defence + +Keep validation where untrusted input enters. Delete repeated internal checks only after tracing the runtime guarantee through every supported entry and mutation path. A TypeScript annotation, cast or assertion signature alone does not enforce a value. + +```ts +// Before, inside a private operation. +if ( + typeof config.timeoutMs !== 'number' || + !Number.isFinite(config.timeoutMs) +) { + throw new Error('Invalid timeout'); +} +return waitForReply(config.timeoutMs); + +// After, only with the runtime guarantee below established. +return waitForReply(config.timeoutMs); +``` + +The guarantee must show that every entry uses a validator enforcing a finite numeric timeout, the operation cannot receive unchecked construction, and the value cannot become invalid after validation. Keep the check when configuration is mutable or another entry bypasses parsing. + +Retain boundary validation for network payloads, persisted data, environment values and third-party responses. Retain permission, balance and state checks whose truth can change between validation and use. Remove duplicated parsing only when retaining one parse preserves error timing and precedence. + +Trust established invariants rather than trusting internal type declarations unconditionally. + +## Reuse a predicate's complete guarantee + +Check the actual library or native predicate before adding or retaining another guard. JavaScript's [Number.isFinite](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite) rejects every non-number without coercion, so a separate type check on the same stable value is redundant. + +```ts +// Before. +if (typeof value !== 'number' || !Number.isFinite(value)) reject(); + +// After. +if (!Number.isFinite(value)) reject(); +``` + +Keep nullability checks needed before accessing a property and checks that supply required static narrowing. Preserve evaluation count when property reads involve getters or proxies. The global `isFinite` coerces input and cannot supply the same guarantee. Generalise this technique by reading the predicate's contract, rather than assuming every validator checks types. + +## Delete empty error machinery and unjustified fallbacks + +Remove a catch that only rethrows the same error. + +```ts +// Before. +try { + return await sendInvoice(invoice); +} catch (error) { + throw error; +} + +// After. +return await sendInvoice(invoice); +``` + +Keep logging, translation, cleanup, cancellation and required async boundaries. Removing `await` can change stack traces or whether `finally` runs before completion. Keep error identity and propagation where they are contractual. + +A fallback may be redundant when the missing case is unreachable under established runtime construction. If it handles supported missing or invalid input, retain its outcome. Turning a silent fallback into a thrown error is a behaviour change. Identify that decision separately, rather than hiding it inside cleanup. + +For **Incomplete Library Class**, first check whether the installed library already supplies the required operation. Remove bespoke adaptation only when its semantics match. Keep the smallest adapter for an actual external mismatch. + +## Replace explanatory narration with names + +Rename a misleading symbol instead of adding a comment to explain it. Delete commented-out code, stale instructions and narration of obvious statements. + +```ts +// Before. +// Calculate the number of visible rows. +const n = visibleRows.length; + +// After. +const visibleCount = visibleRows.length; +``` + +Keep public contract documentation, legal headers, factual external constraints and explanations of irreducible algorithms. Comments recording an important reason can be the least code needed to preserve maintainability. + +## Delete tests that add no unique protection + +Trace the behaviour each test actually observes. Keep the smallest set protecting supported behavioural promises. Delete obsolete fixtures, private-delegation assertions and duplicate cases only when useful protection survives elsewhere or they protect no supported behaviour. + +```ts +// Before, after a forwarding class is removed. +expect(reader.read).toHaveBeenCalledWith(bytes); + +// After, retaining the existing entry-point assertion. +expect(parseInvoice(bytes)).toEqual({ id: 'INV-7', total: 125 }); +``` + +The illustrated literal must come from an independently established contract or worked example. If the entry-point assertion already exists, delete the obsolete delegation test. If the obsolete test held unique protection, propose transferring that protection before removing it. This example is a proposed transformation, not authority to write new tests during read-only review. + +Keep legitimate absence assertions such as no charge on rejection, exact public outputs and useful compile-time checks. A test count or coverage improvement is not the objective. Keep cases exercising distinct user behaviour even when setup looks duplicated. + +Reuse existing behavioural checks or a focused safe comparison for preservation evidence. Follow [$test-design](../../test-design/SKILL.md) for testing applicability and quality. Leave a preservation gap visible rather than expanding the test scope. diff --git a/skills/code-cleanup/references/control-flow-and-algorithms.md b/skills/code-cleanup/references/control-flow-and-algorithms.md new file mode 100644 index 0000000..c567bf0 --- /dev/null +++ b/skills/code-cleanup/references/control-flow-and-algorithms.md @@ -0,0 +1,112 @@ +# Control flow and algorithms + +Read when nested branches, repeated outcomes, control flags or bespoke algorithms obscure a complete operation. + +## Replace Nested Conditional with Guard Clauses + +Handle rejection cases first, leaving a direct successful path. Preserve the first failing reason, condition evaluation and effects. + +```ts +// Before. +if (customer.active) { + if (!customer.suspended) return makeOffer(customer); + return { kind: 'suspended' }; +} +return { kind: 'inactive' }; + +// After. +if (!customer.active) return { kind: 'inactive' }; +if (customer.suspended) return { kind: 'suspended' }; +return makeOffer(customer); +``` + +An inactive suspended customer must still receive `inactive`. Keep structured nesting or `try/finally` where an early return would bypass resource release. A getter or condition can have effects, so moving or duplicating it needs evidence. + +## Consolidate Conditional Expression and Duplicate Conditional Fragments + +Join checks with one outcome when their short-circuit order is equivalent. Move a repeated fragment to one location only when it runs on exactly the same paths, at the same point relative to other effects. + +```ts +// Before. +if (invoice.paid) return { kind: 'blocked' }; +if (invoice.cancelled) return { kind: 'blocked' }; + +// After, retaining left-to-right short-circuiting. +if (invoice.paid || invoice.cancelled) return { kind: 'blocked' }; +``` + +```ts +// Before. +if (express) { + total += expressFee; + emitTotal(total); +} else { + total += standardFee; + emitTotal(total); +} + +// After. +total += express ? expressFee : standardFee; +emitTotal(total); +``` + +Keep separate branches when messages, failures or sequencing differ. Moving `emitTotal` before the addition changes its payload. Moving it outside a branch that can return changes whether it runs. Keep readable statements rather than compressing several decisions into nested ternaries. + +## Remove Control Flag + +Replace a flag that merely steers loop termination with direct control flow. Preserve iteration, return values and any work after the loop. + +```ts +// Before. +let found = false; +let match; +for (const row of rows) { + if (!found && row.id === id) { + match = row; + found = true; + } +} +return match; + +// After, for an ordinary array with no observable later iteration. +return rows.find((row) => row.id === id); +``` + +Check sparse arrays, custom iterators, getters and predicate effects. A loop that must consume the remaining stream cannot stop at the first match. A flag representing persistent domain state earns a different treatment from a local termination flag. + +## Centralise variant data + +Replace repeated literal mappings with one owner. Use a local exhaustive switch when variants have different effects. Data can replace constant-only strategies without creating callback registries. + +```ts +// Before, duplicated across consumers. +if (tier === 'express') return 1; +if (tier === 'standard') return 3; +return 7; + +// After, with the same unknown-tier outcome. +const deliveryDays = new Map([ + ['express', 1], + ['standard', 3], +]); +return deliveryDays.get(tier) ?? 7; +``` + +Keep the mapping in one owner and reuse it across consumers. For runtime-validated closed variants, a record can cover every variant and use direct lookup. For open input, retain the unknown case. Plain `record[tier]` can change the fallback or expose prototype properties. A short local branch can be simpler than a table plus validation when no duplication exists. + +## Substitute Algorithm and reuse existing operations + +Prefer an existing project or standard-library operation over a hand-written equivalent. Check equality, ordering, duplicates, missing values, Unicode, failure behaviour and required performance. A shorter implementation with different semantics is not cleanup. + +```ts +// Before, unique ids in first-seen order using primitive equality. +const unique: string[] = []; +for (const id of ids) { + if (!unique.includes(id)) unique.push(id); +} + +// After. +const unique = [...new Set(ids)]; +``` + +This equivalence is for strings. Do not extend it to structural deduplication of objects. Replacing a streaming operation with a materialised collection may violate memory or latency requirements. Include such costs in preservation evidence. diff --git a/skills/code-cleanup/references/deletion-and-layers.md b/skills/code-cleanup/references/deletion-and-layers.md new file mode 100644 index 0000000..fef3225 --- /dev/null +++ b/skills/code-cleanup/references/deletion-and-layers.md @@ -0,0 +1,82 @@ +# Deletion and layers + +Read when unused paths, speculative options, pass-through abstractions or inheritance add machinery. + +## Remove Dead Code and Speculative Generality + +Delete code without a supported use, including unused helpers, parameters, modes, factories and dependencies. Apply **YAGNI** to planned flexibility that no present contract requires. Trace runtime discovery, external consumers and import-time effects first. A published API is not dead merely because the repository has no caller. + +The illustrative internal API below has only one caller. The option was added for an abandoned feature, and every call passes `false`. + +```ts +// Before. +function renderInvoice(invoice: Invoice, includeDraft: boolean) { + if (includeDraft) return renderDraft(invoice); + return renderFinal(invoice); +} +renderInvoice(invoice, false); + +// After. +renderFinal(invoice); +``` + +Use **Remove Parameter**, then inline the empty forwarding function. Remove `renderDraft`, its private-only imports, fixtures and registrations once no supported path remains. Include changes in unchanged callers. Keep the option when a CLI, configuration file or external consumer can still select it. A default value does not prove the alternative unused. + +For equivalent internal old and new APIs, inventory callers, migrate them in the same transformation and delete the old implementation. Keep a compatibility path only for an evidenced external or transition contract. Removing a legacy API without migrating its callers leaves the cleanup unfinished. + +## Inline Function, Inline Class and Remove Middle Man + +Remove a forwarding layer that owns no policy, translation, state or useful dependency boundary. Migrate callers to the complete existing operation. + +```ts +// Before, each class has its own file and registration. +class InvoiceReader { + read(bytes: string) { + return parseInvoice(bytes); + } +} +class InvoiceService { + constructor(private reader: InvoiceReader) {} + read(bytes: string) { + return this.reader.read(bytes); + } +} +const invoice = service.read(bytes); + +// After. +const invoice = parseInvoice(bytes); +``` + +Delete both classes, files, exports and registrations. Check construction, discovery and any import-time work. Compare caller knowledge before and after. Keep a layer that hides a vendor protocol, owns caching or enforces a rule. A single caller or implementation does not invalidate such a boundary. + +Inlining must preserve evaluation count, exceptions and effects. Replacing `const value = expensiveRead(); return format(value, value);` with two calls to `expensiveRead()` changes behaviour and work. Keep the local value. + +## Collapse Hierarchy and Replace Subclass with Fields + +Merge a subclass with its parent when their separate identity has no supported meaning. Replace constant-only variants with data when that deletes constructors, overrides and registrations. + +```ts +// Before, private classes instantiated only by one local selector. +class StandardDelivery { + days() { + return 3; + } +} +class ExpressDelivery { + days() { + return 1; + } +} +const delivery = + tier === 'express' ? new ExpressDelivery() : new StandardDelivery(); +return delivery.days(); + +// After, preserving the original fallback for all other tiers. +return tier === 'express' ? 1 : 3; +``` + +Keep real variant behaviour. Check `instanceof`, reflection, serialised type identifiers, subclass hooks and external construction before removing class identity. A new strategy hierarchy for two constants restores the machinery being removed. + +## Delete an operation whose result is unused + +An unused return value does not make a call dead. `loadPlugin()` may register handlers, warm a cache or fail early on invalid configuration. Before deleting the call or its import, trace its effects and error contract. Keep those effects in the surviving path, or retain the operation. Delete a pure computation only when neither its value nor its failure is part of supported behaviour. diff --git a/skills/code-cleanup/references/ownership-and-state.md b/skills/code-cleanup/references/ownership-and-state.md new file mode 100644 index 0000000..ff0af69 --- /dev/null +++ b/skills/code-cleanup/references/ownership-and-state.md @@ -0,0 +1,86 @@ +# Ownership and state + +Read when repeated knowledge, scattered phases, leaked representation or mutable relationships inflate a capability. + +## DRY and Move Function or Method + +Consolidate one domain rule with its owner. **DRY** removes repeated knowledge, not every similar expression. Use **Move Function**, **Move Method** or **Hide Delegate** when consumers reconstruct an owner's decision or navigate private representation. + +```ts +// Before, repeated by a toolbar and a menu. +button.disabled = document.status !== 'published' || document.locked; +menu.disabled = document.status !== 'published' || document.locked; + +// After, both use the document's existing eligibility operation. +button.disabled = !document.canArchive(); +menu.disabled = !document.canArchive(); +``` + +If the owner lacks that operation, a single local predicate can earn its cost by replacing the repeated rule. Include its full cost. Keep the archive command's own current-state enforcement. Eligibility may change after rendering. Moving the rule must preserve rejection precedence and messages, not invent a richer error model. + +Do not merge similar predicates for independent policies. `canArchive` and `canPublish` can look alike today yet belong to different contracts. A generic `canPerform(action, flags)` can add dispatch and caller knowledge instead of removing duplication. + +## Gather one capability and delete fragmented APIs + +**Shotgun Surgery** occurs when one rule requires scattered edits. Temporal decomposition splits ownership by execution phase. Consolidate shared grammar and lifecycle behind a complete operation. + +```ts +// Before, callers know the required sequence across three modules. +const raw = invoiceLoader.load(bytes); +const decoded = invoiceDecoder.decode(raw); +return invoiceValidator.validate(decoded); + +// After, one module owns the grammar and private sequence. +return parseInvoice(bytes); +``` + +Migrate every internal caller, then delete obsolete phase classes, public intermediate types and registrations. Private phases can remain if they clarify substantial work. Preserve parsing failures, validation order and effects. An externally supported intermediate operation may need to survive. + +Unify alternative internal classes or paired hierarchies only when they represent the same capability or variation. Similar methods on unrelated external libraries justify an adapter only if repeated adaptation exists. + +## Separate independent knowledge + +**Divergent Change** means an owner changes for unrelated reasons. Extract a complete concern when it simplifies each caller contract. A billing module that also translates a carrier's label protocol may benefit from one carrier adapter. A cohesive large algorithm does not benefit from extraction solely because it is long. + +For **Refused Bequest**, narrow an inherited contract or replace inheritance with delegation when the subtype rejects the base promise. Count forwarding methods and new seams as costs. Keep framework inheritance that honours the actual contract. Prefer deleting an unnecessary hierarchy over replacing it with several composition layers. + +## Replace Derived Variable with Query + +Store one authoritative value and derive its cheap projections. Delete the duplicated field, setters, invalidation paths and synchronisation tests together. + +```ts +// Before. +this.visibleRows = rows.filter(isVisible); +this.visibleCount = this.visibleRows.length; +// Other mutations must also remember to update visibleCount. + +// After. +this.visibleRows = rows.filter(isVisible); +get visibleCount() { return this.visibleRows.length; } +``` + +Keep a cache for measured cost or an evidenced observation contract. A getter can change snapshot timing, serialisation or notification semantics. If those are unknown, mark the candidate's preservation gap rather than assuming equivalence. + +## Remove Temporary Field and shrink mutable scope + +Move per-operation scratch state from fields to locals when it has no persistent lifecycle. This removes reset paths and interference between calls. + +```ts +// Before, a synchronous private operation uses a scratch field. +this.total = sum(rows); +return formatTotal(this.total); + +// After. +const total = sum(rows); +return formatTotal(total); +``` + +Trace all readers before deleting the field. Keep state that is observed across calls. Prefer values returned from an operation over mutations of shared scratch objects when that reduces coordination. Preserve object identity where callers observe it. + +## Simplify representation and arguments + +Remove unused arguments or derive owner-held values before grouping parameters. **Introduce Parameter Object** earns its cost for a real **Data Clump**, such as the same date range repeatedly passed and validated together. A bag of unrelated options hides a long parameter list. + +For **Primitive Obsession**, choose the smallest representation that removes repeated interpretation or invalid internal combinations. If `completed` always equals `completedAt !== null`, keep one authoritative field and derive the other. If distinct variants own different data and transitions, a discriminated union can replace synchronised flags. Preserve wire schemas through existing translation, or identify the required compatibility decision. A new wrapper type around every primitive creates more code without necessarily reducing a rule. + +A **Data Class** is useful as a transport record. Move behaviour to it only when consumers repeatedly own its domain rules. Keep independent scalar inputs and plain records where their operations are already simple and total. diff --git a/skills/code-cleanup/references/refactorings.md b/skills/code-cleanup/references/refactorings.md new file mode 100644 index 0000000..aef629d --- /dev/null +++ b/skills/code-cleanup/references/refactorings.md @@ -0,0 +1,29 @@ +# Refactoring for less code + +Use **refactoring** to change structure while preserving supported behaviour. **Subtract before adding**. Demand a present purpose for each piece of machinery. Aim for fewer decisions, layers and mutable relationships, with direct code that remains easy to read. + +Use the **deletion test**. Imagine removing a module. Does unnecessary complexity disappear, or does essential complexity spill into callers? Delete the former. Keep or deepen the latter. A smell is a diagnostic question, not a compulsory extraction or a finding by itself. + +## Technique families + +Consider every family relevant to the scope. Read its reference when matching shapes appear, before proposing the transformation. The references contain original illustrative examples, preservation conditions and cases where keeping the code is simpler. + +| Observed shape or smell | Techniques to consider | Read | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| Dead Code, Speculative Generality, unused modes or parallel legacy paths | Remove Dead Code, Remove Parameter, migrate callers and delete the complete obsolete path | [Deletion and layers](deletion-and-layers.md) | +| Lazy Class, Middle Man, pass-through helpers, constant-only subclasses | Inline Function or Method, Inline Class, Remove Middle Man, Collapse Hierarchy, Replace Subclass with Fields | [Deletion and layers](deletion-and-layers.md) | +| Long Method, nested conditionals, duplicated outcomes, control flags | Guard Clauses, Consolidate Conditional Expression, Consolidate Duplicate Conditional Fragments, Remove Control Flag | [Control flow and algorithms](control-flow-and-algorithms.md) | +| Repeated Switches, branch-heavy mappings, bespoke collection algorithms | Centralise real variant knowledge, Substitute Algorithm, reuse an existing operation | [Control flow and algorithms](control-flow-and-algorithms.md) | +| Duplicate Code, Feature Envy, Message Chains, Inappropriate Intimacy | Move Function or Method, Hide Delegate, consolidate one rule with its owner | [Ownership and state](ownership-and-state.md) | +| Shotgun Surgery, temporal decomposition, Alternative Classes with Different Interfaces, Parallel Inheritance Hierarchies | Gather one capability, unify equivalent internal APIs, remove duplicated variation | [Ownership and state](ownership-and-state.md) | +| Divergent Change, Large Class, Refused Bequest | Separate a complete independent concern, narrow inheritance or use delegation when it reduces burden | [Ownership and state](ownership-and-state.md) | +| Temporary Field, duplicated derived values, synchronised booleans | Replace Derived Variable with Query, shrink mutable scope, use one authoritative representation | [Ownership and state](ownership-and-state.md) | +| Long Parameter List, Data Clumps, Primitive Obsession, Data Class | Remove or derive arguments, Introduce Parameter Object only for a real concept, move repeated domain knowledge | [Ownership and state](ownership-and-state.md) | +| Repeated validation, silent fallback, catch-and-rethrow, custom adaptation | Establish runtime guarantees, delete redundant handling, retain necessary boundary adaptation | [Boundaries and protection](boundaries-and-protection.md) | +| Comments, brittle or duplicate tests, repeated fixtures | Improve names, delete narration and obsolete scaffolding, preserve unique behavioural protection | [Boundaries and protection](boundaries-and-protection.md) | + +## Apply the judgement + +Name the burden removed and the supported contract retained. Similar text can express independent policies. A single caller can still need a deep boundary. A long cohesive function can be simpler than many fragments. A plain record can be the right transport type. Keep those forms when the proposed alternative merely relocates complexity. + +Use an earned extraction for hidden knowledge, real variation or independent responsibility. Introduce a richer model only when it deletes repeated rules, impossible internal combinations or lifecycle machinery. Count the new type, helper, file and caller knowledge as part of its cost. Keep useful validation and current-state checks when uncertainty or mutation remains. diff --git a/skills/code-cleanup/references/review.md b/skills/code-cleanup/references/review.md new file mode 100644 index 0000000..7ed7eb2 --- /dev/null +++ b/skills/code-cleanup/references/review.md @@ -0,0 +1,37 @@ +# Independent cleanup review + +Find ambitious, concrete simplifications in the supplied candidate. Review read-only, without further delegation. Write only your temporary report and disposable probe artefacts. Preserve source, tests, snapshots, dependencies, Git state and durable data. Run a safe focused probe only to settle a concrete uncertainty. Leave repairs and the full check suite to the caller. + +## Inspect and challenge + +1. Read the packet, repository instructions and behavioural authorities. Confirm the candidate and scope. Requirements and documented contracts govern supported behaviour. Existing structure and comments are claims to examine. +2. Inventory all in-scope source and associated tests and configuration. For a diff, inspect complete affected files and trace the whole capability through entry points, owned rules, effects and consumers. Unchanged files can contain the best simplification. For a whole-codebase request, cover every owned capability. Inspect generated or third-party code through its source or contract, rather than proposing hand edits to generated output. +3. Read [the technique index](refactorings.md). Consider every relevant family, loading its reference when the observed code shape matches. Account for every file, class, helper, option, branch and test. Ask what supported use or hidden knowledge earns its existence. Seek transformations that delete whole paths, repeated decisions, layers or synchronisation work. A local rename pass is insufficient while structural opportunities remain. +4. Trace ordinary and implicit uses before proposing deletion. Check exports, framework discovery, reflection, manifests, configuration and import-time effects. A search with no matches is a lead, not proof of disuse. Follow proposed caller migrations through orphaned files, exports, registrations, tests and dependencies. +5. Falsify each candidate. Look for useful policy, genuine variation, external compatibility, ordering or lifecycle guarantees that justify the structure. Preserve results, errors, effects, state, ordering and required performance. Explain how existing checks observe that contract. Distinguish source reasoning, supplied check evidence and probes actually run. Compilation alone does not demonstrate equivalence. + +Apply **YAGNI** to speculative machinery and **DRY** to repeated knowledge. Prefer deletion, consolidation and direct code before extraction. Keep a new boundary only when it removes more reader burden than it adds. Count layers to trace and mutable state to hold. A lower line count or metric cannot justify dense code or displaced complexity. + +## Build the report + +Use [the report template](../assets/cleanup-report.md). Create a unique file such as `code-cleanup-.md` in the OS temporary directory. Record a compact candidate identity rather than a table of file hashes. Put a file path and verified line or symbol in every candidate index row. Use repository-relative paths in the index and absolute paths in the details. Keep one candidate per coherent transformation, including all related-file changes. Merge overlapping observations. Order by maintenance benefit, then strength of preservation evidence. Include every justified candidate without a quota. + +Use these cleanup priorities, independent of defect severity or authorisation: + +| Priority | Concrete benefit | +| -------- | ------------------------------------------------------------------------------------------------- | +| High | Removes substantial machinery, a parallel implementation or a rule scattered across a capability. | +| Medium | Removes meaningful local duplication, indirection, branching or state management. | +| Low | Removes a small evidenced burden through a narrow change. | + +State confidence through the preservation evidence, without numerical scores. Include a concrete promising candidate whose preservation is uncertain, with the exact gap and resolving check or decision beside it. Mark it `Needs evidence`. Reserve `Supported` for transformations whose preservation is backed by traced contracts and consumers. Both still need caller verification after implementation. Omit speculation without demonstrated simplification benefit. + +If a candidate changes supported behaviour, identify the separate decision rather than prescribing it as cleanup. Record a discovered defect only as a concrete out-of-scope limitation. Keep this a cleanup review. + +## Complete the review + +Make a final pass over the scope inventory and technique families. Follow every proposed removal to its newly orphaned artefacts. Continue until that pass reveals no missed supported or concrete uncertain candidate. List inspected scope, family coverage, probes and material limitations compactly. Avoid repeating each symbol solely to prove coverage. + +Use `No findings.` only when a completed review has no justified candidates. Omit candidate details for that result and keep the coverage proportionate to scope. Missing authority, unavailable source or uninspected scope must remain explicit. Save the report, read it back and verify its candidate identity, candidate index, details and coverage agree. Confirm the reviewed source has not changed during the review. If it has, refresh the affected inspection or mark the report incomplete. + +Return only the report's absolute path. If saving fails, return the exact blocker. Stop without editing or adjudicating the code. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index b0a8565..ba60439 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,79 +1,26 @@ --- name: code-review -description: Reviews a fixed code change through isolated specification and engineering-standards agents. Use when a fixed candidate needs independent diagnostic review. -metadata: - type: utility -disable-model-invocation: true +description: Review code independently when a file, module, branch diff or codebase needs assessment against behavioural intent and engineering standards. --- -# Code Review +# Code review -Independently diagnoses one fixed code change against intended behaviour and engineering standards, returning falsifiable suggestions for its caller to adjudicate. +Save one severity-ranked report from **independent Spec and Standards assessments**. Preserve the code and every supported finding. The caller owns adjudication and action. -## Process +## Inputs -### 1. Fix the candidate and authorities +Take the review scope from the request. Accept a file, module, diff or whole codebase. Resolve ambiguous scope before dispatch. An empty diff has no change to review. Existing code needs no diff. -Use the caller's pinned candidate when supplied; otherwise resolve one exact non-empty diff, revision range, branch comparison, pull-request revision, repair, or local candidate. Capture its patch, changed and in-scope untracked paths, complete changed files, relevant source and tests, repository state, and exact revision identifiers where available. Ask when the target is materially ambiguous. Return the exact blocker when it is empty or cannot be fixed. +## Method -Resolve intended behaviour from an implementation-independent authority such as a specification, ticket, acceptance criteria, confirmed request, contract, or another project source. When none is reasonably available, omit Spec and continue Standards without inferring intent from code, commits, or implementation rationale. +1. **Fix the candidate.** Inventory the in-scope source, tests and configuration. Record resolved revisions, comparison semantics and working-tree contents, including staged, unstaged and in-scope untracked files. Keep a path and content fingerprint inventory to detect movement. Include surrounding contracts and consumers needed to understand the scope. +2. **Separate the briefs.** Give both reviewers actual source paths, candidate identity, scope, applicable repository instructions and [review instructions](references/reviewer.md). Give Spec the confirmed request, ticket, specification, acceptance criteria and published behavioural contracts, with [Spec instructions](references/spec.md). Give Standards repository conventions, architecture decisions and relevant check or measurement evidence, with [Standards instructions](references/standards.md). **Exclude the ticket, specification and request from Standards**, including their contents in summaries or check evidence. Exclude conversation history, implementation rationale, proposed findings and prior conclusions from both briefs. +3. **Dispatch fresh.** Spawn separate read-only agents with no inherited conversation history. Run both in parallel when behavioural authority exists. Otherwise skip Spec and record why. Each reviewer follows its assigned instructions without further delegation. Self-review cannot replace either assessment. +4. **Collect and consolidate.** Require complete scope accounting and evidenced findings. Return missing coverage or fields to the same reviewer. Read [the report contract](assets/review-report.md), then combine only the same defect and corrective outcome. Preserve supported disagreements and lone-reviewer findings. Do not adjudicate findings using the implementation conversation or replace independent judgement with your preferred verdict. +5. **Verify and save.** Recheck revisions, comparison, paths and content fingerprints, including inspected context files. Mark affected assessments stale if the candidate moved and identify the reviewed and current state. Save the consolidated report to a unique Markdown file in the OS temporary directory. Read it back and verify identity, assessment status, coverage, findings and deduplication. -Resolve applicable repository instructions, conventions, architecture decisions, configured checks, affected contracts and consumers, and supplied quality evidence. The review basis is explicit and sufficient to understand every changed line in context. +## Finish -### 2. Prepare isolated review packets +Return **only the absolute report path**. If no report can be saved, return the exact blocker. Leave repair, finding dispositions, approval and publication to the caller. -Give both applicable packets the fixed candidate, complete changed files and necessary surrounding source, their own authorities and criteria, the consequence ranking and finding format below, and a read-only boundary. - -Direct the Spec reviewer to account for every applicable requirement in code and retained tests, account for every introduced behaviour against authority, and follow affected contracts, states, data shapes, errors, effects, and consumers far enough to find missing, partial, conflicting, excessive, or regressed behaviour. Trace distinct success, failure, retry, and concurrent paths when the authority distinguishes them. When an external effect precedes durable state or acknowledgement, trace failure after the effect and before that record or response, including what a retry repeats. Report separate suggestions when a different triggering state, violated requirement, consequence, or narrow corrective outcome survives review, even if the evidence overlaps another suggestion. - -Direct the Standards reviewer to understand every changed line in its necessary context and assess: - -- correctness and regression risk; -- the smallest coherent scope and absence of speculative or superseded work; -- repository, language, and framework conventions; -- changed-test validity, independent oracles, behavioural durability, and meaningful failure detection; -- modular ownership, interface depth, dependencies, and change locality; -- repository-required and changed-risk harness selection, measurement-path integrity, and honest evidence limits; and -- recognised maintainability shapes and specialist risks exposed by the change. - -Require the Standards reviewer to load and apply `$modular-design` and `$test-design`. When a concrete maintainability shape needs recognised vocabulary, load [Code Smells](references/CODE-SMELLS.md); use it to investigate a mechanism and consequence, never as finding authority or a removal checklist. - -Require the Standards reviewer to invoke `$measure-code-complexity` against the fixed candidate and comparison base with read-only authority. Treat its current output as diagnostic evidence: inspect each trigger in source and test context, and retain a review suggestion only when a concrete maintainability consequence survives falsification. Report unavailable or incomplete measurement in the review limitations. - -### 3. Run independent reviews - -Give each applicable packet to a separate fresh agent and run them in parallel where possible. Do not substitute coordinator self-review. If fresh-agent execution is unavailable, mark the affected axis not performed and state the exact limitation. - -Each reviewer may run a safe, focused, non-mutating command only to confirm or falsify a concrete concern. It does not repeat the implementation's whole quality portfolio, edit code or tests, update snapshots or baselines, install dependencies, modify durable data, or repair a finding. - -Before retaining a suggestion, try to disprove it through contradicting authority, existing handling, repository-sanctioned exceptions, surrounding code, a focused counterexample, and the strongest benign interpretation. Omit unsupported generic advice, tooling-enforced trivia, speculative best practice, and a pre-existing issue unless the candidate introduces, worsens, or makes it newly consequential. - -Rank each surviving suggestion by consequence: - -- **High:** a credible path to materially wrong required behaviour, including a duplicated, lost, or misdirected external effect; security or privacy compromise; data loss or corruption; major production or reliability failure; or a structural, test, or evidence defect that makes the change untrustworthy. -- **Medium:** a concrete defect, regression risk, or significant maintainability, modularity, test-quality, or harness-integrity weakness with a bounded material consequence. -- **Low:** a local evidenced issue whose narrow correction has a concrete benefit. - -Priority orders attention only; it does not direct remediation. - -### 4. Preserve the results and candidate - -Validate only that each result uses the required fields. Return an incomplete result to that same reviewer for structural completion from its original packet. Do not substantively re-review, merge, deduplicate, suppress, or cross-axis rerank the independent results. - -Reinspect the fixed revisions, diff, paths, and in-scope untracked content. When the candidate drifted, preserve each affected frozen result, prefix it with `Status: stale`, state the changed paths and basis mismatch, and stop without retargeting it. - -## Handoff - -State the exact frozen scope, behavioural authority or reason Spec was omitted, Standards authorities, probes and limitations, unperformed axes, and scope drift. Return `## Standards` and `## Spec` separately; for an applicable current clean axis use `No findings.` and for an omitted, unperformed, or stale axis state that status explicitly. - -Format each suggestion as: - -```markdown -### [high|medium|low] Concise finding - -- Evidence: exact code location, applicable authority or criterion, and observed fact -- Consequence: concrete behavioural or code-health impact -- Suggested direction: narrow outcome that addresses the concern without prescribing an unverified patch -``` - -End with axis-specific counts and review scope. Return the reviewers' substance and ordering unchanged. Do not repair the candidate, adjudicate suggestions, issue a verification, completion, or approval verdict, publish comments, or alter pull-request state. The caller owns validation, adjudication, remediation, re-review, verification, and publication. +**Done only when** applicable fresh assessments cover the fixed scope, the verified report preserves every supported finding without duplicates, and the candidate remains current. An incomplete or stale assessment must identify its unreviewed scope or drift and cannot claim `No findings.`. diff --git a/skills/code-review/agents/openai.yaml b/skills/code-review/agents/openai.yaml index 6c2a385..13fe716 100644 --- a/skills/code-review/agents/openai.yaml +++ b/skills/code-review/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Code Review' - short_description: 'Independently review a fixed code change' -policy: - allow_implicit_invocation: false + short_description: 'Save independent Spec and Standards findings' diff --git a/skills/code-review/assets/review-report.md b/skills/code-review/assets/review-report.md new file mode 100644 index 0000000..4db9fdb --- /dev/null +++ b/skills/code-review/assets/review-report.md @@ -0,0 +1,39 @@ +# Review report contract + +Each assessment supplies findings in the format below. The consolidator saves one report with a compact candidate identity, requested scope, comparison where relevant, authorities, assessment statuses, inspected and uninspected scope, probes and material limitations. Keep the fingerprint inventory as verification evidence rather than a large table in the report. + +Record Spec as skipped when behavioural authority is unavailable. Distinguish complete, incomplete and stale assessments. A skipped Spec assessment does not invalidate a completed Standards assessment. Use `No findings.` only for completed current assessments with no surviving concern. A report is not an approval or proof that the code is defect-free. + +## Rank by consequence + +| Severity | Consequence | +| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| High | Material requirement failure, security or privacy compromise, data loss, duplicated effects, major reliability failure, or a structural or evidence defect that makes the candidate untrustworthy. | +| Medium | Bounded behavioural defect, regression risk or meaningful maintenance burden with an evidenced causal path. | +| Low | Local evidenced issue with a concrete benefit from a narrow correction. | + +Order findings by severity, then strength of evidence. Express confidence through the evidence and its limits, without numerical scores. Severity orders attention and grants no remediation authority. + +```markdown +### [High|Medium|Low] Concise finding + +- Axis: spec | standards | spec, standards +- Location: verified absolute file path and line or symbol +- Issue: the specific defect or maintenance burden +- Evidence: applicable authority, observed facts and reachable triggering case or structural demonstration +- Effect: concrete behavioural or maintenance consequence +- Direction: narrow corrective outcome, without an unverified patch +``` + +## Deduplicate without losing findings + +Merge only the same defect with the same corrective outcome. Keep both axis labels and all material evidence and consequences. Use the strongest supported severity. Shared locations, symptoms or terminology do not establish duplication. + +| Independent observations | Consolidated result | +| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Spec finds a retry charges twice. Standards finds the same path lacks idempotency. | One finding with both axes and the required retry behaviour and engineering evidence. | +| Spec finds missing rejection. Standards finds a resource leak on that branch. | Two findings because rejection and resource cleanup require different corrections. | +| One reviewer supports a concern and the other reports no findings. | Retain the concern. Silence is not contrary evidence. | +| Reviewers disagree about a contract or remedy. | Preserve supported concerns and explain the disagreement. Return missing evidence to its reviewer. | + +Consolidation preserves independent judgement. The caller decides which findings to accept, reject or investigate. diff --git a/skills/code-review/references/CODE-SMELLS.md b/skills/code-review/references/CODE-SMELLS.md deleted file mode 100644 index 3185738..0000000 --- a/skills/code-review/references/CODE-SMELLS.md +++ /dev/null @@ -1,28 +0,0 @@ -# Fowler Code Smells - -Load this complete second-edition catalogue only when a concrete maintainability shape needs recognised diagnostic vocabulary. Each cue identifies a code shape to investigate, not a finding or authority by itself. Test the relevant benign interpretation against the scoped code, repository authorities, and concrete consequence. - -1. **Mysterious Name** — An identifier does not communicate its role, meaning, or unit in the surrounding domain. A repository-defined term or tightly conventional local name may already be precise. -2. **Duplicated Code** — Materially similar behaviour appears in multiple locations that may need to evolve together. Superficially similar code may represent different responsibilities or change for different reasons. -3. **Long Function** — A function contains enough distinct steps, branches, or levels of abstraction to obscure its purpose or invariants. A cohesive linear workflow may be clearer when read together. -4. **Long Parameter List** — Numerous inputs or recurring groups of related values make a callable's contract hard to understand or use safely. A boundary function may intentionally expose independent dependencies. -5. **Global Data** — Broadly accessible data creates hidden dependencies across consumers. Immutable constants or configuration with explicit ownership may not carry that risk. -6. **Mutable Data** — In-place changes or aliases make state transitions and observers difficult to reason about. Mutation with a tight owner, lifetime, and invariant may remain local and explicit. -7. **Divergent Change** — One module changes for several unrelated responsibilities within the scoped work. Multiple edits may still serve one cohesive responsibility. -8. **Shotgun Surgery** — One conceptual change requires coordinated edits scattered across many locations. Layer-specific or generated representations may legitimately change together. -9. **Feature Envy** — Behaviour depends more on another object's data or decisions than on its own owner. Orchestration, presentation, and adapter code may properly coordinate across a boundary. -10. **Data Clumps** — The same group of values repeatedly travels or appears together as an implicit concept. Coincidental co-occurrence or a constrained public boundary may not establish one shared abstraction. -11. **Primitive Obsession** — Primitive values repeatedly carry domain states, units, validation, or rules that callers must remember. Simple, local, already-constrained values may remain unambiguous. -12. **Repeated Switches** — Conditional dispatch over the same discriminator recurs across the change. A single exhaustive boundary mapping may keep variation explicit without scattering it. -13. **Loops** — Imperative iteration obscures the transformation, selection, or control intent being performed. Stateful traversal, early exit, or measured performance constraints may make the loop the clearest form. -14. **Lazy Element** — An abstraction carries little distinct behaviour, policy, or information. A small named boundary may still express a domain concept or preserve a necessary interface seam. -15. **Speculative Generality** — Flexibility, parameters, hooks, or abstractions serve only hypothetical requirements. A current specification, compatibility contract, or demonstrated extension point may make the flexibility concrete. -16. **Temporary Field** — An object's field is meaningful only during particular modes or phases, leaving other states uncertain. An explicit lifecycle with guarded access may make those states intentional. -17. **Message Chains** — A caller navigates through a sequence of collaborators and therefore depends on their internal structure. A stable data traversal or intentional fluent interface may expose that chain as its contract. -18. **Middle Man** — An element mostly forwards requests without contributing policy, translation, or information. A boundary may still provide isolation, authorisation, observability, or compatibility. -19. **Insider Trading** — Modules rely on each other's internal knowledge or backchannels beyond their stated contracts. A deliberately shared internal protocol may have clear ownership and stability. -20. **Large Class** — A class accumulates enough unrelated state or behaviour to obscure its responsibility and invariants. A cohesive aggregate may need central ownership to protect one invariant boundary. -21. **Alternative Classes with Different Interfaces** — Types serving the same conceptual role expose unnecessarily different contracts. Similar-looking types may instead represent distinct domain roles. -22. **Data Class** — A type mainly stores data while its rules or meaningful behaviour live elsewhere. A transfer object, event, or serialisation record may be intentionally data-only. -23. **Refused Bequest** — A subtype rejects, ignores, or cannot honour a substantial part of its inherited contract. A narrow implementation may still fully honour the interface actually promised. -24. **Comments** — Comments compensate for code whose intent or structure is unclear, or merely restate what it does. Rationale, safety constraints, protocol details, and public contracts may require commentary beyond the code. diff --git a/skills/code-review/references/reviewer.md b/skills/code-review/references/reviewer.md new file mode 100644 index 0000000..7d03dc4 --- /dev/null +++ b/skills/code-review/references/reviewer.md @@ -0,0 +1,19 @@ +# Independent review + +Review only your assigned axis. Use [the finding format and severity definitions](../assets/review-report.md). Return your axis, candidate identity, authorities, coverage, probes, limitations and all supported findings. Do not spawn another reviewer. + +## Inspect and falsify + +Read every in-scope source file and enough surrounding code, consumers, tests and configuration to understand the contracts. For a diff, understand every changed line in complete-file context. For a codebase, account for every owned capability. Inspect generated and third-party code through its source or contracts rather than proposing hand edits to generated output. + +Trace each concern through a reachable execution path or demonstrate a concrete maintenance burden. Try to disprove it using existing handling, contrary evidence, sanctioned exceptions, a focused counterexample and the strongest benign interpretation. A smell, weak metric or preferred alternative is a lead, not proof. Omit generic advice, speculative improvements and trivia already enforced by tooling. + +For a diff, retain pre-existing issues only when the change worsens them or makes them newly consequential. For a file, module or codebase review, include existing in-scope issues. A concern outside the requested scope belongs in limitations, not the findings list. + +Run a safe focused probe only to settle a concrete concern. Confine writes to disposable scratch artefacts and reports. Preserve source, tests, snapshots, dependencies, Git state and durable data. Do not repair, install tools or repeat the caller's full check suite. Distinguish source reasoning, supplied evidence and probes actually run. + +## Complete coverage + +Revisit the inventory and every applicable review lens. Follow unresolved leads until they are supported, disproved or blocked by a named evidence gap. Continue until a final coverage pass exposes no missed in-scope concern. Include every supported finding without a quota. + +State uninspected scope and material evidence limits explicitly. Use `No findings.` only for a completed current assessment with no surviving concern. Return missing prerequisites without inventing intent, measurements or a clean verdict. diff --git a/skills/code-review/references/spec.md b/skills/code-review/references/spec.md new file mode 100644 index 0000000..148c31d --- /dev/null +++ b/skills/code-review/references/spec.md @@ -0,0 +1,9 @@ +# Spec assessment + +Account for every applicable requirement against implementation-independent behavioural authority. Code and author rationale cannot establish missing intent. State the specific limit when authority is partial or contradictory. + +Trace supported entries through contracts, states, data, errors, effects and consumers. Find omitted, partial, incorrect, excessive and regressed behaviour. For a diff, cover every introduced behaviour and its effect on existing promises. For existing-code scope, assess its current behaviour against applicable promises. + +Follow success, failure, retry and concurrent paths wherever they can break a promise. When an external effect precedes acknowledgement or durable state, inspect failure between them and what a retry repeats. Check that supplied tests assert the required outcome rather than repeat the implementation. + +For each finding, cite the authoritative requirement, reachable triggering case, implementation evidence, consequence and corrective outcome. Leave engineering quality to Standards unless the same defect also breaks a requirement. diff --git a/skills/code-review/references/standards.md b/skills/code-review/references/standards.md new file mode 100644 index 0000000..c5a5557 --- /dev/null +++ b/skills/code-review/references/standards.md @@ -0,0 +1,11 @@ +# Standards assessment + +Assess engineering quality independently of the ticket, specification and request. Use applicable repository instructions, documented standards, architecture decisions, supported interfaces, consumers and conventions. Local sanctioned variations govern over generic heuristics. Existing patterns alone do not justify a defect. + +Read [$modular-design](../../modular-design/SKILL.md), [$test-design](../../test-design/SKILL.md) and [$code-cleanup](../../code-cleanup/SKILL.md). Apply their applicability rules and judgement within this review's read-only boundary. Do not dispatch cleanup or execute design, test-writing or implementation workflows. Load their references when the observed code needs the detailed technique. + +Inspect correctness, consistency, regressions, security, privacy, reliability, modular ownership, information hiding, dependency direction, interface depth, locality, unnecessary complexity, test validity and evidence integrity. Investigate relevant specialist risks, including resource lifetime, concurrency, performance, accessibility and compatibility. Trace actual inputs to dangerous sinks or effects rather than report hypothetical misuse. + +Actively seek meaningful simplifications, including duplicated rules, leaked representations, split ownership and unnecessary layers. Demonstrate the maintenance burden and narrow corrective outcome. Working code can still contain a quality defect. Keep opportunities that remove a concrete burden even without immediate behavioural failure. Leave a dedicated ambitious cleanup review to its caller. + +Inspect supplied measurements in source context. A score alone is not a finding or a gate. Check what was measured and whether the evidence supports the claim. Report missing evidence instead of inventing a threshold or starting new measurement runs. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 907fd6a..c1ded77 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -1,17 +1,26 @@ --- name: commit -description: Creates atomic Conventional Commits for eligible reviewed work while preserving unrelated changes. Use when completed local work is ready to record. -metadata: - type: utility -disable-model-invocation: true +description: Record all uncommitted branch changes as atomic Conventional Commits when asked to commit directly or by a publishing workflow. --- # Commit -Records eligible local work in coherent commits without disturbing unrelated changes. +Record **all uncommitted changes** in atomic commits by intent, including work from earlier sessions. Respect Git's normal ignore rules. -## Process +## Inputs -Assign the entire process below to one fresh agent with the user's request and repository path; when already inside the fresh agent for an enclosing operation, perform it there. Use only repository evidence to inspect the complete Git state and diffs, group eligible work by intent into atomic **Conventional Commits**, preserve unrelated staged, unstaged, and untracked work, and let commit hooks run. The work is already reviewed and verified; do not run tests, project checks, or implementation verification. Verify only each commit and the final Git status, then return only the hashes, titles, and remaining work. Retain only that result. +The actual diffs determine what needs recording. -Stop without changing the implementation, pushing, or opening a pull request. +## Method + +1. Inspect the status, staged and unstaged diffs, and untracked files. Account for every change, regardless of its session or author. +2. Group changes by intent. Keep coupled changes together and separate independent outcomes. Stage each exact group while keeping the remaining groups intact. +3. Review the exact patch and use a **Conventional Commit** title, `type: description` or `type(scope): description`. Choose the type from the change and a meaningful scope when useful. Keep the description short and imperative, without a trailing full stop. For example, `fix(parser): reject invalid dates` or `docs: explain configuration`. Mark breaking changes with `!` before the colon or a `BREAKING CHANGE:` footer. Add a body only when necessary context or repository guidance requires it. +4. Let normal commit hooks run. If a hook fails, report the failure and remaining work. Preserve the changes and stop without bypassing the hook or altering implementation to satisfy it. +5. Verify each recorded commit and the remaining status. Inspect hook edits and repeat until every change is recorded. Keep existing history intact. + +## Finish + +Return commit hashes and titles, or report that there is nothing to commit. Report any blocker and remaining work. + +**Done only when** every uncommitted change is recorded and the final status is clean under normal ignore rules. Stop before pushing or opening a pull request. diff --git a/skills/commit/agents/openai.yaml b/skills/commit/agents/openai.yaml index e9c29a0..524921e 100644 --- a/skills/commit/agents/openai.yaml +++ b/skills/commit/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Commit' - short_description: 'Create atomic conventional commits' -policy: - allow_implicit_invocation: false + short_description: 'Commit all branch changes in atomic conventional commits' diff --git a/skills/create-tickets/SKILL.md b/skills/create-tickets/SKILL.md index 9f004e9..e421569 100644 --- a/skills/create-tickets/SKILL.md +++ b/skills/create-tickets/SKILL.md @@ -1,49 +1,27 @@ --- name: create-tickets -description: Creates implementation-ready tickets from approved work. Use when a complete work definition needs vertical decomposition in the project's configured ticket system. -metadata: - type: performer -disable-model-invocation: true +description: Plan and create small vertical implementation tickets when requested work needs an executable breakdown. --- -# Create Tickets +# Create tickets -Turns one **approved work definition** into a confirmed, verified set of small vertical tickets. A work definition may be a document or confirmed conversation whose outcome, scope, behaviour or obligations, material constraints, and solution decisions are complete enough to decompose without invention. +Create a confirmed, verified set of **tracer-bullet vertical slices**. Each ticket must be executable in a fresh conversation from its body and accessible authorities. -## Prerequisites +## Inputs -Read the root `AGENTS.md` for an explicit ticket destination such as `The project uses Linear for tickets.` or `The project uses local Markdown for tickets.` When absent, ask the user which destination the project uses, invoke `$maintain-agents` with the answer, and resume from its result. For an external destination, require its installed integration and writable account; otherwise stop with the exact access needed. Never guess or silently fall back. +Take the work from the request and its supplied context, including a specification or confirmed discussion. Read relevant project guidance, linked authorities and current-system evidence. Resolve missing content rather than require an earlier document. Read the ticket destination from root `AGENTS.md`. Resolve an absent destination through the active dialogue and invoke [$maintain-agents](../maintain-agents/SKILL.md) to record the answer. -## Process +## Method -### 1. Establish the work and destination +1. **Resolve planning gaps.** Invoke [$elicit-with-context](../elicit-with-context/SKILL.md) for requirements exposed by decomposition, slice boundaries and dependencies. Inspect discoverable facts yourself and use [$research](../research/SKILL.md) when external evidence is needed. If new answers change a supplied specification, have the dialogue confirm the correction and update it before publishing dependent tickets. +2. **Slice complete outcomes.** Read [slicing guidance and examples](references/slicing.md) before decomposition. Account for every scoped requirement and acceptance boundary. Find the smallest coherent outcomes that can be demonstrated or verified through the layers they need. Carry required safeguards with the first affected slice. Split separable variants and merge fragments that supply no meaningful intermediate result. Use no estimates. +3. **Order the graph.** Add a hard dependency only for a predecessor outcome required to begin or accept the dependent ticket. Name that outcome. Reject cycles. Propose a topological order with blockers first, distinguishing recommended order from dependencies. Supply numbered titles, delivered outcomes and blockers to the active dialogue for breakdown confirmation. +4. **Make each ticket executable.** Invoke [$write-prose](../write-prose/SKILL.md) with the confirmed set, work definition and [ticket template](assets/ticket-template.md). Add concrete implementation and verification guidance for each slice. Separate fixed requirements from an adaptable implementation plan. Include useful verified entry points and commands, identifying planned structures as proposed. Link precise accessible authority or embed necessary confirmed context from the discussion. End every ticket with observable acceptance checkboxes. +5. **Publish and connect.** Read [destination guidance](references/destinations.md) for the selected destination before writes. Create exactly the agreed set in dependency order, then wire relationships using actual identifiers. When a specification exists, append or reconcile its bottom checklist of ordered ticket links. Initialise new checkboxes unchecked and preserve existing completion state. +6. **Read back and verify.** Read every saved ticket, relationship and specification checklist. Check faithful scope, complete requirement coverage, executable context, unchecked new acceptance, acyclic blockers and valid links. Repair unambiguous in-scope discrepancies. -Use the already-loaded root guidance. Inspect the request, approved work definition, and only the additional linked product, context, decision, research, and current-system evidence needed to understand the work. Treat the definition as authority for intended outcomes and settled constraints, and the repository as evidence of the current system. +## Finish -For an external destination, inspect its native item, body, status, estimate, parent, dependency, and read-back capabilities before planning writes. For local Markdown, use one file per ticket under `docs/features//tickets/`. +Return ordered ticket links, dependency and coverage checks, the specification checklist update and material limitations. Stop before implementation, scheduling, commits or deployment. -### 2. Agree the vertical ticket set - -Map every material requirement, obligation, constraint, solution responsibility, transition, and acceptance boundary in both directions between the work definition and proposed tickets. Form the smallest coherent set in which each ticket delivers one observable outcome or fulfilled contract across every layer it needs. Absorb shared setup into the earliest outcome that needs it. Create separate enabling, migration, or refactor work only when it has an independently necessary, verifiable boundary or preserves a valid compatible intermediate state. - -Size each ticket for one fresh implementation session. Load the [Estimation Reference](assets/estimation-reference.md), assign the lowest defensible **complexity** bucket from `1`, `2`, `3`, `5`, or `8`, and use sibling comparison only as a consistency check. Split any outcome that would exceed `8`, then estimate the resulting slices again. - -Add a blocker only when one ticket cannot honestly begin or meet acceptance before another reaches its accepted outcome. Keep display order, likely sequence, user-journey order, and merely related work out of the dependency graph. State dependency direction explicitly and reject cycles. - -Present only a compact numbered proposal containing each ticket's stable title, vertical outcome, complexity, and `Blocked by` references. Invoke `$elicit-with-context` when supported alternatives require a user decomposition decision. Iterate the compact set until the user confirms the whole proposal; do not synthesize full bodies first. Confirmation authorises the agreed synthesis and writes without another application prompt. If synthesis exposes a material gap, leave the destination unchanged and reopen the affected proposal. - -### 3. Synthesize and write the tickets - -Use the [Ticket Template](assets/ticket-template.md) as the minimum semantic body, omitting only inapplicable conditional content. Embed the necessary confirmed intent and solution context when no durable authority exists; never tell a fresh implementation agent to recover an unavailable conversation. Explain what must be delivered at stable boundaries without prescribing files, classes, framework wiring, code, or an exhaustive test inventory. - -For local Markdown, allocate stable sequential identifiers such as `TKT-001`, use `-.md`, set new tickets to `Todo`, and write reciprocal `Blocked by` and `Blocks` references. The local status vocabulary is `Todo`, `In Progress`, `Done`, and `Cancelled`. - -For an external destination, use the closest established initial native status and map complexity, blocker, blocked, and parent meanings to exact native fields when available. When an exact capability is absent, retain the meaning explicitly in the body and surface the limitation; never substitute a different relation. Do not set priority, assignee, sprint or cycle, milestone, release, or dates unless the approved definition or user supplies them. - -Create and relate exactly the confirmed set. - -### 4. Read back, verify, and stop - -Read every created ticket and relationship back from its destination. Verify the confirmed titles, outcomes, authority or embedded context, requirements, applicable constraints, acceptance criteria, complexity values and ceiling, status, relationship meanings and directions, acyclic dependencies, resolved local references, and two-way work-definition coverage. Correct an exact in-scope discrepancy when the agreed value and target are unambiguous; otherwise stop with the mismatch and required decision or capability. - -Return the created ticket links or local paths, verification performed, capability limitations, source limitations, and unresolved external state. Stop without changing the approved work definition, scheduling or prioritising work, implementing, committing, publishing, releasing, or deploying. +**Done only when** contextual elicitation is complete, every scoped requirement is covered, and all tickets, dependencies and applicable specification links are saved and verified. Missing decisions, access or failed writes leave dependent work incomplete. diff --git a/skills/create-tickets/agents/openai.yaml b/skills/create-tickets/agents/openai.yaml index 4f7072c..391d172 100644 --- a/skills/create-tickets/agents/openai.yaml +++ b/skills/create-tickets/agents/openai.yaml @@ -1,6 +1,3 @@ interface: display_name: 'Create Tickets' - short_description: 'Create implementation-ready vertical tickets' - default_prompt: 'Use $create-tickets to turn this approved work definition into confirmed, implementation-ready tickets.' -policy: - allow_implicit_invocation: false + short_description: 'Plan executable vertical slices and dependencies' diff --git a/skills/create-tickets/assets/estimation-reference.md b/skills/create-tickets/assets/estimation-reference.md deleted file mode 100644 index 1e7418c..0000000 --- a/skills/create-tickets/assets/estimation-reference.md +++ /dev/null @@ -1,28 +0,0 @@ -# Estimation Reference - -Estimate the complexity of the agreed vertical outcome, including the implementation, verification, and rollout obligations needed to accept it. Buckets are stable, ordered comparisons, not ratios, hours, dates, or duration promises. - -## Calibration rule - -Choose the lowest bucket that accounts for the outcome's known behaviour and material difficulty. Raise it only for an explicit driver in the approved work or current-system evidence. A higher bucket needs evidence that the lower bucket does not describe the work. - -- Treat normal traversal through UI, API, persistence, and tests as one vertical outcome, not additive complexity. -- Include routine testing at every level. Raise for difficult states, failure modes, concurrency, compatibility, or specialist quality constraints, not for test quantity alone. -- Use the established patterns and capabilities that apply. Do not estimate an imagined redesign, unknown requirement, or optional robustness. -- Resolve material scope ambiguity before estimating. Use a higher bucket for bounded implementation difficulty, not as a buffer for missing decisions or low confidence. -- Compare sibling tickets after anchoring them. Correct estimates that differ without a material difference in their drivers; do not grade the set on a curve. -- Split work above `8`. Before assigning `8`, also split any independently valuable outcome that removes a distinct risk or preserves a valid intermediate state. - -## Buckets - -The indicators are evidence, not a scorecard. One strong driver can matter more than several routine ones. - -| Bucket | Meaning and evidence | Vertical-slice example | -| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `1` | Routine, direct outcome using an established path. One simple rule or state, no meaningful integration or transition risk, and obvious boundary checks. | Expose an already-stored preference in the existing settings API and UI, and verify that changing it affects the existing behaviour. | -| `2` | Small bounded outcome using established patterns across the layers it needs. May add one simple data or contract change, with few predictable branches and a routine rollout. | Add a new boolean email preference through persistence, the settings API and UI, delivery enforcement, and standard feature tests. | -| `3` | Moderate outcome with a new internal model or contract, several interacting rules or states, or non-trivial boundary verification. Migration or compatibility work is limited and well understood. | Add user-owned saved searches with naming rules, persistence, CRUD through the existing API and UI, ownership checks, and boundary tests. | -| `5` | High-complexity but bounded outcome with a difficult lifecycle, integration, transition, or quality boundary. Evidence may include concurrency or idempotency, timezone or security rules, several failure paths, or substantive design judgement. | Deliver a daily account-summary email at a user's local time, including DST-safe scheduling, duplicate prevention, last-sent status, queued delivery, and failure-boundary tests. | -| `8` | Exceptional coherent outcome with broad system impact or a high-risk transition that cannot be split into independently valid slices. Evidence includes several coupled hard boundaries such as live compatibility, recovery, data correction, and cross-system failure handling. | Replace a live authorisation model while API requests and workers remain active, including compatible reads and writes, backfill verification, cutover, recovery, and rollback. | - -Do not raise a bucket because the ticket touches many files, crosses several application layers, has numerous acceptance criteria, or feels large in prose. Those are consequences of a vertical slice, not complexity evidence by themselves. diff --git a/skills/create-tickets/assets/ticket-template.md b/skills/create-tickets/assets/ticket-template.md index 52a9413..7f3ecc3 100644 --- a/skills/create-tickets/assets/ticket-template.md +++ b/skills/create-tickets/assets/ticket-template.md @@ -1,29 +1,28 @@ -# {TKT-001} — {Ticket title} +# {Ticket ID}: {Outcome title} -- **Status:** {Todo or destination-native status} -- **Complexity:** {1, 2, 3, 5, or 8} -- **Blocked by:** {Ticket references or None} -- **Blocks:** {Ticket references or None} -- **Authority:** {Durable work-definition link and identifiers, or concise embedded authority context} +- **Status:** {Todo or destination-native initial status} +- **Source:** {Precise specification links and IDs, or embedded confirmed context below} +- **Blocked by:** {Ticket links and required predecessor outcomes, or None} -## Outcome +## Outcome and scope -{One independently observable vertical result or fulfilled contract.} +{Why this slice matters, what becomes observable, supported cases and explicit exclusions. Include the required starting state.} -## Context +## Requirements and context -{Only the bounded actors, current state, settled solution constraints, non-goals, and source details a fresh implementation session cannot infer safely.} +{Applicable behaviour, data, shared contracts, constraints and safeguards. Link accessible authorities precisely. Embed necessary confirmed intent and consequential design when no durable source exists.} -## Functional requirements +## Implementation guidance -- {Approved behaviour or rule owned by this ticket.} +{Concrete route through the layers this outcome needs, useful inspected entry points, established patterns, data or interface changes and required migration or integration steps. Distinguish fixed decisions from adaptable suggestions and future structures from existing facts.} -## Non-functional requirements +## Verification - - -- {Constraint in its operating context with an observable response or measure where established.} +{Observable evidence for this slice, relevant test or direct-verification approach, inspected commands and required project checks. State what predecessor capability the verification relies on.} ## Acceptance criteria -- [ ] {Observable pass/fail condition at a user, assistive-technology, contract, event, migration, persistence, provider, or operating boundary.} +- [ ] {Observable pass/fail result and applicable requirement ID} +- [ ] {Material boundary, denial, failure or recovery result} + + diff --git a/skills/create-tickets/references/destinations.md b/skills/create-tickets/references/destinations.md new file mode 100644 index 0000000..79309db --- /dev/null +++ b/skills/create-tickets/references/destinations.md @@ -0,0 +1,33 @@ +# Ticket destinations + +Apply the branch selected by project guidance. Establish access and required capabilities before publishing. Keep exact destination operations in its current tool or CLI documentation. + +## Local Markdown + +Use one file per ticket beside an existing specification in its `tickets/` directory. Without a specification, follow project conventions or default to `docs/features//tickets/`. + +Allocate stable sequential IDs such as `TKT-001` in dependency order, using `-.md`. Preserve existing IDs and status. Start newly created tickets at `Todo`. Local statuses are `Todo`, `In Progress`, `Done` and `Cancelled`. Link blockers to real files and name the predecessor outcome each supplies. + +Before creating files, inspect existing tickets and any specification checklist. Reuse matching work rather than duplicate it. If existing scope differs materially, resolve the difference through the dialogue. Verify every new file and relative link after writing. + +## External tracker + +Inspect the installed integration's writable destination, item body, initial status, parent relationships, blocking links and read-back operations. Missing required access blocks publication to that destination. Report the missing capability rather than switching destination silently. + +Create items in dependency order and record actual identifiers before wiring relationships. Use native blocking links where supported. Otherwise preserve blockers in the body with real links and report the representation limit. Use a native parent only when the source is a suitable existing tracker item. Parentage and blocking are different relationships. + +Apply destination-native initial status. Set other fields only when the user or project guidance supplies them. After a failed or unknown write outcome, inspect existing state before retrying. Verify item bodies and relationships independently. Report created items, remaining writes and mismatches if publication is partial. + +## Specification checklist + +After tickets exist, add or reconcile the specification's last `## Tickets` section in the confirmed order: + +```markdown +## Tickets + +- [ ] [TKT-001: Save and restore a date filter](tickets/TKT-001-save-date-filter.md) +- [ ] [TKT-002: Save a named filter set](tickets/TKT-002-save-named-set.md) +- [ ] [TKT-003: Save and restore a text-query filter](tickets/TKT-003-save-text-query.md) +``` + +Use real external URLs for tracker items and preserve valid unrelated entries. Keep each ticket's acceptance criteria in that ticket. The specification checklist tracks tickets rather than copying their acceptance criteria. Creating tickets does not mark implementation complete. diff --git a/skills/create-tickets/references/slicing.md b/skills/create-tickets/references/slicing.md new file mode 100644 index 0000000..6ef1fbb --- /dev/null +++ b/skills/create-tickets/references/slicing.md @@ -0,0 +1,67 @@ +# Slice the work + +Use **tracer bullets** to deliver narrow, complete paths through the layers they need. A slice should make a meaningful outcome demoable or verifiable from its stated starting state. A completed slice can contribute to a feature without making the entire feature release-ready. + +## Find the smallest meaningful outcome + +Start with the simplest supported end-to-end outcome. Include its data, logic, interface and verification as needed. Split further by independently useful operation, business-rule variation, data variant, interaction or integration. Prefer a split whose later part could be deferred while the earlier part remains a coherent supported capability. + +Stop splitting when another cut produces only a layer, an uncheckable fragment, a duplicated invariant or excessive repeated setup with no useful intermediate result. A ticket touching several layers can be smaller in responsibility than a single-file ticket containing unrelated outcomes. Use outcome, variation and verification to judge size, rather than estimates or fixed file counts. + +Carry ownership, validation, security and required failure guarantees with the first slice that needs them. Narrow supported cases to reduce scope. Every supported case must still satisfy its applicable requirements. + +## Worked splits + +These illustrative outcomes assume the rules described have already been confirmed. They are not default product policies. + +| Feature | Coherent slices | Boundaries to preserve | +| ----------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Room booking | Book one fixed-duration room slot through confirmation. Add cancellation. Add recurring bookings. | The first booking enforces permissions and conflict prevention, with defined failure feedback. Cancellation depends on an existing booking. Recurrence may need separate conflict rules. | +| Catalogue import | Import one CSV schema through validation to stored records. Add another schema. Add preview. | The first import includes agreed duplicate handling, atomic or partial failure and resource limits. Parser, storage and UI are steps inside a slice. | +| Saved searches | Save and restore one supported filter. Add named search sets. Add another filter type. | Ownership and persistence are verified in the first slice. Named sets and another filter may be sibling tickets after that contract exists. | +| Job notifications | Notify completion through one agreed channel. Add another channel. Add preferences. | Each supported channel honours the feature's duplicate-delivery and failure contract. Do not leave required reliability to an undefined later ticket. | + +## A concrete ticket and graph + +Assume an application already has identity, a filter editor and a saved-filter contract. The agreed feature adds one persisted date filter, named sets and text-query filters. + +1. **Save and restore a date filter.** No blockers. Implement persistence, API and editor integration as one outcome. Verify reopening the editor, ownership denial, invalid dates and persistence failure. +2. **Save a named filter set.** Blocked by ticket 1's persisted-filter contract. Add name validation and set selection through the needed layers. +3. **Save and restore a text-query filter.** Blocked by ticket 1's persisted-filter contract. Extend the supported shape and editor. It can proceed independently of named sets. + +A date-filter ticket might contain this body excerpt: + +```markdown +## Implementation guidance + +Extend the established saved-filter representation with the confirmed date range. Connect the existing filter editor to the save and load contract. Keep ownership validation at the existing boundary. Treat storage failure according to REQ-04. Inspect the repository's current persistence and editor entry points before choosing the exact internal edits. + +## Verification + +Exercise saving and reopening through the supported editor. Verify the stored range through a second read. Cover invalid ranges, another user's access and the agreed storage-failure result. Run the project's required checks. + +## Acceptance criteria + +- [ ] Reopening restores the saved date range under REQ-01. +- [ ] Invalid ranges leave the previous saved value unchanged under REQ-02. +- [ ] Another user cannot read or replace the range under REQ-03. +- [ ] A failed save reports the agreed failure and preserves the previous value under REQ-04. +``` + +Replace illustrative rules with the actual authority. Include inspected paths or commands when they help the real implementer. Do not present a hypothetical entry point as existing code. + +“Create the table”, “write the API”, “build the editor” and “test the feature” would usually be horizontal fragments of ticket 1. Keep those steps together. If a reusable external API is itself an agreed capability with independent consumers and acceptance, it can instead justify its own ticket. + +## Enabling work and migrations + +Absorb ordinary setup into the earliest outcome needing it. Separate an enabler only when a necessary contract, risk reduction or compatible state can be verified independently, especially when several slices rely on it. State the dependent feature, exact output and verification. Avoid speculative infrastructure and unrelated cleanup. + +For a broad migration, prefer **expand-contract** when compatibility is required. Add the new compatible form, migrate independently verifiable consumer groups, then remove the old form after all consumers have moved. Each dependency names the state the next ticket needs. + +If no intermediate edit can be verified independently, group the coupled work into one bounded ticket with internal steps and an explicit integration check. Resolve a larger decomposition or different verification boundary with the user instead of representing broken fragments as finished vertical outcomes. Resolve unknown consequential design before ordinary dependent implementation tickets. + +## Audit coverage and dependencies + +Map every scoped requirement to its tickets and every ticket back to its justified source. Several tickets may collectively fulfil a requirement. Check that their union covers its states, variants and constraints without inventing new scope. + +Add an edge for a required predecessor outcome, not simply display order, shared files or shared terminology. If a cycle appears, revisit the boundaries, merge coupled outcomes or settle the shared contract. Among unblocked tickets, recommend an order by value, learning and risk without creating false blockers. diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 6de1def..bf7eb3a 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -1,67 +1,39 @@ --- name: debug -description: Diagnoses software defects and conditionally makes causal, verified repairs. Use for failures, regressions, runtime errors, flaky behaviour, or performance faults. -metadata: - type: performer -disable-model-invocation: true +description: Investigate software defects systematically when reported behaviour, tests, builds, integrations or performance fail their intended contract. --- -# Debug +# Systematic debugging -Diagnoses a defect through discriminating evidence and, when requested, produces one minimal reviewed local repair. +Establish a supported causal mechanism before repairing a defect. Use **systematic debugging**, from root cause investigation through pattern analysis and hypothesis testing to implementation with verification. Prefer the smallest causal repair, including deletion. -## Process +## Inputs -### 1. Fix the outcome and signal +Take the defect and diagnosis or repair intent from the request. Inspect the affected code and failure evidence. Requirements and documented contracts govern intended behaviour. Code and runtime observations establish actual behaviour. Use [$elicit-with-context](../elicit-with-context/SKILL.md) for material user-held gaps that inspection cannot resolve. -Read the request, repository instructions, expected and observed behaviour, failing evidence, environment, relevant authorities, current code, and tests. Resolve whether the requested outcome is diagnosis only or diagnosis plus repair. Invoke `$elicit-with-context` only when a material user-held fact or decision remains. +Preserve unrelated work and original failure evidence. Keep production and external systems read-only. Protect secrets and unnecessary personal data in probes, captures and reports. -Keep production and external systems read-only and within explicit authority. When diagnosis or mitigation needs external mutation, report the required action and stop; production mitigation, deployment, and monitoring remain outside this skill. +Create a unique Markdown **causal record** in the OS temporary directory for every investigation, or resume the supplied record. Keep its absolute path available. On resumption, read it and referenced evidence, then recheck relevant code and environment for drift before relying on prior conclusions. -Define the best available **signal**: a focused test, command, error, trace, captured artefact, controlled benchmark, safe observation, or measured failure rate. Record its invocation or provenance, input, environment, expected result, observed result, and fidelity limits. Run it before changing implementation when safe. Prefer a sharp repeatable reproduction, but accept authorised captured, external, or probabilistic evidence when that is the honest boundary. Preserve the original unminimised signal through the investigation. If no evidence can distinguish the reported defect, leave implementation unchanged and return the exact gap and next smallest experiment. +## Method -### 2. Narrow the cause +1. **Investigate the root cause.** Read [investigation and patterns](references/investigation-and-patterns.md). Read the actual errors and relevant traces. Establish an exact failure signal through a test, command, capture, safe observation or measured rate. Record its invocation or provenance, inputs, relevant environment, expected and observed results, and fidelity limits. Run it before repair when safe. Preserve the original unminimised scenario. Trace the failing path and bad state backwards to the first broken invariant. Inspect relevant code, dependency, configuration and state changes. If evidence cannot distinguish the reported defect, gather the missing observation before dependent conclusions. +2. **Analyse the pattern.** Find a credible working example or authoritative reference and understand its complete relevant path, lifecycle and dependencies. Compare inputs, state, configuration, ordering and implementation. Account for material differences without dismissing small ones. Record when no credible comparator exists. A difference or first bad revision identifies a candidate, not its cause. +3. **Test hypotheses.** Read [hypothesis experiments](references/hypothesis-experiments.md). Keep grounded, ranked alternatives in the causal record. State one active mechanism, supporting evidence, prediction and falsifier before the smallest discriminating observation or intervention. Control material conditions, inspect the result and update the account. Undo owned edits motivated by rejected hypotheses. Revisit the oracle and shared premises when attempts contradict the account or expose new coupling. Persist until the mechanism explains the exact failure and trigger, observations establish the relevant transition, and discriminating evidence favours it over the strongest alternatives, or a concrete evidence, access or authority blocker prevents progress. Prefer controlled runtime confirmation whenever safely available. Decisive captured evidence or direct analysis can suffice. Suggestive evidence remains a hypothesis. +4. **Implement and verify.** For diagnosis-only work, return the supported account and stop. For an authorised repair, first consider removing unnecessary work or correcting the existing rule or state owner. Check related occurrences of the demonstrated pattern within the authorised capability and report wider discoveries separately. Restore owned experimental edits before handing off. Invoke [$implement](../implement/SKILL.md) with the causal record, intended contract, original signal, minimal repair boundary and verification obligations. It owns testing eligibility, implementation, simplification, checks and independent review. Require verification against the original failure and relevant causal observations before treating the change as working. If they contradict the account, record the result, revert that attempt's owned repair edits and resume investigation. Check the final candidate against the original signal after implementation finishes. -Build a small model of the relevant path, contracts, state, boundaries, and recent code, configuration, dependency, environment, data, or workload changes. Treat recent change, suspicious location, correlation, and a passing retry as hypotheses or observations, never as proof. +Load specialised guidance as soon as its signal appears. Combine techniques when they answer different unresolved questions. -Maintain one compact investigation record containing observations, a small ranked set of causal hypotheses, the active prediction, the experiment, its result, its implication, and contradictory evidence. Test one prediction at a time with the smallest safe experiment that distinguishes credible alternatives. Prefer changing one factor while preserving the signal's material conditions. +| Signal | Read | +| -------------------------------------------------------------- | -------------------------------------------------------------------- | +| Large trigger or regression between reliably classified states | [Reduction and bisection](references/reduction-and-bisection.md) | +| Timing, order, randomness, load or shared-state dependence | [Nondeterministic faults](references/nondeterministic-concurrent.md) | +| Latency, throughput, retention, exhaustion or resource cost | [Performance faults](references/performance-resource.md) | -Select the reference whose trigger matches the current uncertainty and load only that reference. Return its evidence to this causal loop before selecting another: +Record the initial signal and intended contract, append each experiment's prediction and actual result, and update the supported account, owned edits, blockers and next step before pausing or handing off. Link evidence by path or provenance and preserve rejected hypotheses. Keep the record concise rather than copying full tool transcripts. Use [$research](../research/SKILL.md) when a material external-knowledge question needs a durable cited investigation. -| Evidence shape | Load | -| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -| Multiple plausible explanations remain | [Hypothesis-Driven Experiments](references/HYPOTHESIS-EXPERIMENTS.md) | -| A component, pipeline, request, or data path has observable boundaries | [Boundary Isolation](references/BOUNDARY-ISOLATION.md) | -| Reliable known-good and known-bad ordered states exist | [Change Bisection](references/CHANGE-BISECTION.md) | -| A large input, state, sequence, trace, or change set can be reduced | [Delta Debugging](references/DELTA-DEBUGGING.md) | -| Invalid state appears downstream of where it originated | [Origin Tracking](references/ORIGIN-TRACKING.md) | -| A credible working case can be compared with the failing case | [Comparative Debugging](references/COMPARATIVE-DEBUGGING.md) | -| Existing evidence cannot distinguish the active hypotheses | [Instrumentation and Debuggers](references/INSTRUMENTATION-DEBUGGERS.md) | -| Outcome depends on timing, order, randomness, load, or shared state | [Nondeterministic and Concurrent Faults](references/NONDETERMINISTIC-CONCURRENT.md) | -| The signal is latency, throughput, contention, exhaustion, leakage, or resource cost | [Performance and Resource Faults](references/PERFORMANCE-RESOURCE.md) | +## Finish -When the shape is unclear, verify the signal and inspect recent changes, then compare a working case, isolate boundaries, reduce the reproducer, trace the first invalid state, and finally add targeted probes. Enter nondeterministic or performance guidance immediately when its trigger applies. Combine techniques only when each answers a distinct unresolved question. +Remove owned temporary probes and experimental edits while preserving needed evidence. Update the causal record and return its absolute path with the cause and trigger, original signal, decisive experiments and rejected alternatives, repair if requested, verification and implementation results, and remaining limitations. For blocked work, name the missing evidence or access and next discriminating experiment. -Continue until the evidence explains the causal mechanism and accounts proportionately for the strongest alternatives. A root cause may be a set of jointly necessary conditions rather than one deepest line. If the next discriminating experiment is unsafe, unavailable, outside authority, or no longer economical, stop with the supported findings, uncertainty, and exact next experiment. Invoke `$research` only when a material external-knowledge question requires a durable cited report. - -### 3. Close diagnosis or repair one cause - -Remove owned temporary probes, captures, fixtures, and experimental edits, retaining a diagnostic only when project authority makes it durable and safe. State the supported cause, mechanism, trigger conditions, evidence for and against the material alternatives, contradictions, confidence boundary, and remaining unknowns. For diagnosis-only work, state that implementation was not changed and stop. - -For an authorised repair, apply `$modular-design` to keep the change with the natural owner and limit propagation. Select one minimal change directed at the supported cause; exclude unrelated cleanup, broad refactoring, speculative hardening, and other plausible defects. - -Apply `$tdd` when its prerequisites hold. The established signal supplies Red only when it independently specifies the desired observable behaviour and fails for that reason; a crash, trace, log, profile, or implementation-derived expectation does not automatically qualify. Otherwise use the strongest existing project-native feedback without claiming TDD or creating project-wide test infrastructure. - -Run the original signal against the repair. Retain the attempt only when the result changes as the causal account predicted. When it does not, record the contradiction, revert only the exact changes owned by that attempt without disturbing pre-existing work, and return to the causal loop. Do not stack another unsupported fix. - -### 4. Review and verify the local repair - -Freeze the complete candidate, intended-behaviour authority, causal account, original signal, regression evidence, selected quality evidence, changed and untracked paths, and repository state. Invoke `$code-review` on that exact candidate. Adjudicate every finding against the request, authorities, causal evidence, and current code. Correct supported required findings, ask the user about material behaviour, architecture, or scope decisions, and reject unsupported or out-of-scope findings with concrete evidence. - -After any candidate change, rerun the original signal and affected harnesses, re-freeze the candidate, and repeat independent review. Complete only when the current candidate has no unresolved required finding; the focused regression passes; the original unminimised signal changes as predicted; applicable repository and risk-triggered checks have been run; and unavailable or inconclusive evidence remains explicit. Do not turn green checks into universal proof. - -## Handoff - -Return the requested outcome; expected and observed behaviour; authority and environment boundary; original signal; hypotheses, predictions, experiments, contradictions, and reverted attempts; causal mechanism or exact evidence gap; retained change and regression protection; quality evidence and limitations; review scope and dispositions; residual risk; and next discriminating experiment or follow-up. Include one brief prevention observation only when it follows directly from the established cause; do not create an automatic postmortem or wider programme. - -For diagnosis-only work, state that implementation was unchanged. Stop after the diagnosis or reviewed verified local repair without committing, changing tracker state, publishing, deploying, mutating production, or monitoring. +**Done only when** the causal record is current and the requested outcome meets its gate. Diagnosis must explain a supported mechanism and its evidence limits. An authorised repair must change the original failure and relevant causal observations as predicted, and `$implement` must have met its completion gate. Blocked or unverified work remains incomplete. Stop at the local result. Urgent mitigation, unrelated cleanup, commit, publication, deployment and monitoring are outside this contract. diff --git a/skills/debug/agents/openai.yaml b/skills/debug/agents/openai.yaml index 412d7c6..7a4ca78 100644 --- a/skills/debug/agents/openai.yaml +++ b/skills/debug/agents/openai.yaml @@ -1,5 +1,3 @@ interface: - display_name: 'Debug' - short_description: 'Find causal defects and verify local repairs' -policy: - allow_implicit_invocation: false + display_name: 'Systematic Debugging' + short_description: 'Investigate root causes and verify minimal repairs' diff --git a/skills/debug/references/BOUNDARY-ISOLATION.md b/skills/debug/references/BOUNDARY-ISOLATION.md deleted file mode 100644 index 0809d81..0000000 --- a/skills/debug/references/BOUNDARY-ISOLATION.md +++ /dev/null @@ -1,17 +0,0 @@ -# Boundary Isolation - -Use this reference when a failure crosses a short component, process, service, pipeline, request, or data path with observable boundaries. The result is the earliest boundary where a valid state or invariant becomes invalid. - -## Narrow the path - -Map the smallest relevant path and define the expected input, output, state, and invariant at each material boundary. Follow one request, event, job, transaction, or datum using its correlation identity and environment or version context. - -For a short path, walk boundaries in order. For a large path with trustworthy midpoints, observe the midpoint, keep the failing half, and repeat. Inject or replay known data only when doing so preserves the conditions relevant to the hypothesis. - -Capture only the fields needed to distinguish the current hypotheses. Treat absent, sampled, delayed, or uncorrelated telemetry as an evidence limitation rather than a healthy result. Redact secrets and unnecessary personal or production data; retain an external pointer when the workspace cannot store the artefact safely. - -## Transfer the result - -A divergent boundary localises the fault but does not explain the internal cause. Record the last valid state, first invalid state, correlation evidence, replay fidelity gaps, and components excluded. Then return to the main causal loop and use origin tracking, comparison, or a targeted experiment inside the remaining boundary. - -Stop when one component or transition remains, or when the next observation needs unavailable access or external mutation. Remove owned temporary boundary probes after use. If a repair does not move the earliest divergence as predicted, reject the repair hypothesis. diff --git a/skills/debug/references/CHANGE-BISECTION.md b/skills/debug/references/CHANGE-BISECTION.md deleted file mode 100644 index 83427f0..0000000 --- a/skills/debug/references/CHANGE-BISECTION.md +++ /dev/null @@ -1,17 +0,0 @@ -# Change Bisection - -Use this reference when the same crisp property is reliably absent in one ordered state and present in another. States may be revisions, versions, configurations, datasets, or ordered inputs. The result is the smallest reliably classified transition. - -## Freeze the classifier - -Define one command or observation that classifies a state as good, bad, or untestable against the original signal. Confirm trustworthy endpoints before searching. A flaky, environment-sensitive, or changed classifier invalidates ordinary bisection; stabilise it or route to nondeterministic guidance first. - -Test the midpoint, retain its exact state and verdict, keep the half containing the transition, and repeat. For Git history, prefer the repository's supported build and test procedure; use `git bisect run` only when the command's exit statuses faithfully encode good, bad, and untestable. Preserve the log and exit bisect state when finished. - -Apply any compatibility adjustment consistently and keep it separate from the states under test. Do not discard unrelated work or rewrite a user's worktree to make historical states runnable; use an isolated worktree or disposable copy when necessary. - -## Interpret the boundary - -Skipped or broken states near the boundary may leave several candidate transitions. Non-monotonic behaviour or interacting changes may make the result misleading. Environment drift can cause an old state to receive the wrong verdict. - -The first bad state is localisation evidence, not automatic root cause. Inspect the semantic difference and run a discriminating experiment that connects it to the causal mechanism. Stop when the transition is reliable or when the remaining untestable range is explicit. diff --git a/skills/debug/references/COMPARATIVE-DEBUGGING.md b/skills/debug/references/COMPARATIVE-DEBUGGING.md deleted file mode 100644 index da6bfbe..0000000 --- a/skills/debug/references/COMPARATIVE-DEBUGGING.md +++ /dev/null @@ -1,15 +0,0 @@ -# Comparative Debugging - -Use this reference when a credible working version, implementation, configuration, platform, tenant, request, or input can be compared with the failing case. The result is the first material divergence relevant to the defect. - -## Control the comparison - -State why the comparator is trustworthy for the property under investigation. Hold inputs and environment stable where possible and list intentional differences before observing internal state. - -Compare external outcomes first. Then place equivalent checkpoints along both paths and narrow toward the first difference in output, state, dependency, configuration, control flow, or timing. When many differences exist, partition them or combine this technique with bisection. Reduce a differing case when a smaller comparison retains the same divergence. - -## Test the divergence - -Either side can be wrong, both can share a defect, and intentional or nondeterministic differences create noise. A difference therefore produces a causal candidate, not a verdict. - -Record the shared conditions, relevant differences, first divergence, and why later differences are consequences rather than causes. Return to origin tracking or a controlled hypothesis experiment that introduces or removes the divergence and predicts the original signal. Stop when the first explainable divergence is found or the comparator proves unreliable. diff --git a/skills/debug/references/DELTA-DEBUGGING.md b/skills/debug/references/DELTA-DEBUGGING.md deleted file mode 100644 index dfc36ee..0000000 --- a/skills/debug/references/DELTA-DEBUGGING.md +++ /dev/null @@ -1,17 +0,0 @@ -# Delta Debugging - -Use this reference when a large input, request, configuration, dataset, trace, sequence, state, or change set can be classified automatically or cheaply. The result is a smaller case that preserves the same failure. - -## Reduce against one oracle - -Freeze a classifier that distinguishes the exact failure from a pass and from an invalid or unresolved candidate. Remove a large partition, run the unchanged classifier, retain the removal only when the same failure remains, and increase granularity when a coarse partition cannot be removed. Continue with the reduced case. - -Preserve ordering and dependencies that make a candidate valid. Record unresolved candidates separately; do not treat them as passes or failures. For generated or fuzzed input, retain the seed and original counterexample before reducing it. - -Manual minimisation uses the same discipline: remove one coherent dimension at a time, retest, and keep only evidence-preserving reductions. Do not rewrite the oracle to accommodate a smaller case. - -## Preserve representativeness - -The result is minimal only relative to the tried partitions and granularity; it need not be globally smallest. Interdependent elements can prevent further reduction, and a reduced case can omit the interaction that makes the production scenario representative. - -Stop when no remaining unit can be removed at the chosen granularity without losing the exact signal, or when further reduction is more expensive than investigating the bounded case. Use the reduced case to localise or form hypotheses, but keep the original unminimised signal for repair verification. diff --git a/skills/debug/references/HYPOTHESIS-EXPERIMENTS.md b/skills/debug/references/HYPOTHESIS-EXPERIMENTS.md deleted file mode 100644 index d0941cb..0000000 --- a/skills/debug/references/HYPOTHESIS-EXPERIMENTS.md +++ /dev/null @@ -1,23 +0,0 @@ -# Hypothesis-Driven Experiments - -Use this reference when more than one causal explanation remains. The result is one observation that changes the ranked hypothesis set. - -## Form the prediction - -For each plausible cause, state the mechanism and the observation it predicts. Keep a small alternative set grounded in the current evidence; a file, line, component, or recent commit without an explanation is only a location. - -Choose the experiment that best partitions the credible alternatives for the least cost and risk. Prefer an invariant check, focused input change, controlled environment difference, intermediate value, or boundary observation over a repair attempt. Hold other material conditions stable. - -Record: - -- **Hypothesis:** the proposed causal mechanism. -- **Prediction:** the result expected if it is true and, where useful, if it is false. -- **Experiment:** the one controlled observation or intervention. -- **Result:** the exact observation, including conflicting or inconclusive data. -- **Implication:** supported, rejected, or not discriminated, plus the next ranked alternatives. - -## Interpret honestly - -An experiment supports only what its controls and oracle distinguish. A symptom disappearing after a code change may reflect masking, altered timing, or a bypassed path. A negative result is useful when the experiment was capable of exposing the proposed mechanism. - -Remove an owned experimental change after its observation unless it becomes the separately authorised causal repair. Stop when one causal account explains the full signal and trigger conditions and proportionate alternatives have been excluded, or when the next discriminating experiment crosses a named evidence, safety, or authority boundary. diff --git a/skills/debug/references/INSTRUMENTATION-DEBUGGERS.md b/skills/debug/references/INSTRUMENTATION-DEBUGGERS.md deleted file mode 100644 index 5f96641..0000000 --- a/skills/debug/references/INSTRUMENTATION-DEBUGGERS.md +++ /dev/null @@ -1,24 +0,0 @@ -# Instrumentation and Debuggers - -Use this reference when existing evidence cannot distinguish the active hypotheses. Tools are probes for a stated question, not the debugging method itself. The result is the smallest new observation that changes the causal model. - -## Select the probe - -Choose the instrument whose observation matches the question: - -| Question | Probe | -| ----------------------------------------------------------- | ------------------------------------------------------------------------- | -| Which local state or branch first violates an invariant? | Conditional breakpoint, watchpoint, or stack inspection | -| Where does one request cross a process or service boundary? | Correlated logs, metrics, trace, or narrow state endpoint | -| Which operation consumes CPU, memory, I/O, locks, or time? | Matching profiler, counter, or targeted runtime trace | -| Does a known fault class occur? | Repository-supported detector such as a race, memory, or query diagnostic | - -Place the fewest probes at boundaries, decisions, and state transitions that partition the hypotheses. Capture only the needed input, output, identity, correlation, time, and environment. Establish measurement overhead when the probe can affect the signal. - -## Preserve the evidence boundary - -Pausing can invalidate real-time or concurrent behaviour; logging can change timing; profiles are samples; multiple diagnostic tools can interfere. Prefer non-stopping tracepoints or record/replay only when the project and platform support them. - -Do not log credentials, tokens, keys, connection strings, or unnecessary personal data. Follow project retention and access rules, and keep production systems read-only. Tag temporary probes so they can be found and removed. - -Stop when the observation supports, rejects, or fails to discriminate the active hypotheses. Remove owned probes and sensitive captures after use, or retain a diagnostic deliberately within project authority. If the probe only produces more undirected data, sharpen the prediction before adding another. diff --git a/skills/debug/references/NONDETERMINISTIC-CONCURRENT.md b/skills/debug/references/NONDETERMINISTIC-CONCURRENT.md deleted file mode 100644 index db65ac2..0000000 --- a/skills/debug/references/NONDETERMINISTIC-CONCURRENT.md +++ /dev/null @@ -1,24 +0,0 @@ -# Nondeterministic and Concurrent Faults - -Use this reference when nominally identical inputs produce different outcomes or the failure rate changes with timing, order, isolation, load, logging, randomness, clocks, network, shared state, or scheduling. The result is a controlled failure rate or a replayable causal execution, not one passing retry. - -## Measure and partition - -Run the exact trigger repeatedly. Record attempts, failures, seed, input, order, clock, load, resources, environment, and any captured schedule. Establish a baseline failure rate before changing code. - -Vary one likely source at a time: - -- replay or sweep randomness and generated inputs; -- permute test order and isolate shared files, ports, processes, or state; -- control time and wait for observable conditions rather than guessed delays; -- constrain parallelism or use a repository-supported race detector; -- capture, replay, or systematically explore schedules when tooling permits; or -- control load, resource pressure, network, filesystem, and dependency state. - -Use stress or injected delay only to amplify and capture a failure. Preserve the seed, order, trace, schedule, or invariant violation that makes the execution useful. - -## Interpret probability - -A passing sample does not prove absence. Added sleeps, longer timeouts, logging, and reduced parallelism can hide a race without removing its cause. Race detectors and schedule explorers cover only the behaviour and nondeterminism they observe or control. - -Stop reproduction when a failing execution is replayable or the measured rate is stable enough to compare discriminating experiments. Verify a repair first against the preserved failing execution, then repeat the original trigger under the same controls and report failures per attempts and remaining statistical uncertainty. Reject a repair that does not change the causal execution or measured rate as predicted. diff --git a/skills/debug/references/ORIGIN-TRACKING.md b/skills/debug/references/ORIGIN-TRACKING.md deleted file mode 100644 index 5054b75..0000000 --- a/skills/debug/references/ORIGIN-TRACKING.md +++ /dev/null @@ -1,23 +0,0 @@ -# Origin Tracking - -Use this reference when a bad value, state transition, side effect, or decision is observed far downstream from where it arose. The result is the earliest demonstrated valid-to-invalid transition and its responsible conditions. - -## Trace backwards - -Start at the first observed invalid state. Identify its data definitions, callers, controlling conditions, prior state, and external inputs. Move backwards through the call and data flow, checking the relevant invariant at each step, until the last valid and first invalid states are adjacent. - -Choose the smallest project-native observation that can expose the transition: - -- a conditional breakpoint for a local state and condition; -- a watchpoint for an unexpected mutation; -- a targeted trace for a call or effect path; -- record/replay or reverse execution when the platform supports it; or -- a focused dynamic or static slice when many statements may influence the value. - -Record both the responsible operation and the inputs, state, ordering, or control condition that made it harmful. An assignment or stack frame alone is not a causal account. - -## Bound the claim - -Static slices may over-approximate, debugger facilities have platform and threading limits, and tracing can perturb execution. If instrumentation changes the failure, route that evidence through nondeterministic guidance. - -Stop at the earliest invalid transition that explains the downstream symptom. Return the transition and conditions to the hypothesis loop and test whether controlling them changes the original signal as predicted. diff --git a/skills/debug/references/PERFORMANCE-RESOURCE.md b/skills/debug/references/PERFORMANCE-RESOURCE.md deleted file mode 100644 index 79a28c4..0000000 --- a/skills/debug/references/PERFORMANCE-RESOURCE.md +++ /dev/null @@ -1,25 +0,0 @@ -# Performance and Resource Faults - -Use this reference when the defect is latency, throughput, CPU, memory, allocation, I/O, contention, queueing, exhaustion, leakage, query cost, or scale behaviour. The result is a measured causal connection between responsible work and the original user-visible regression. - -## Establish a representative signal - -Define the workload, environment, known-good baseline or expected threshold, warm-up, measurement interval, repetitions, and distribution that distinguishes the fault. Control input size and shape, concurrency, cache state, runtime version, machine resources, data volume, and other material conditions. Route a noisy classifier through nondeterministic guidance before trusting it. - -For early systemic triage, inspect utilization, saturation, and errors for each relevant resource. Then choose the measurement that matches the suspected cost: - -| Suspected cost | Evidence | -| ------------------------------------- | --------------------------------------------------------------- | -| CPU or call-path work | Sampling or instrumenting profile under the controlled workload | -| Memory or allocation | Heap, allocation, retention, or growth measurement | -| I/O, network, queue, or lock pressure | Resource counter and targeted trace | -| Database execution | Actual plan, cardinality, I/O, locks, and query timing | -| Version or configuration regression | Stable differential benchmark or change bisection | - -Connect the hotspot, plan, wait, saturation, or growth to the user-visible signal through a controlled workload or intervention. A hotspot is where cost was observed, not automatically why the system is slow. - -## Verify like with like - -Record measurement overhead and production cost. Long averages can hide bursts, profiles are samples, and one constrained resource can be traded for another. - -After one causal repair, rerun the identical workload and controls. Compare the full relevant distribution and low-level causal metric, then run functional regression evidence. Stop only when both move as predicted under the original representative workload. A faster result obtained by changing behaviour, workload, environment, or measurement does not verify the repair. diff --git a/skills/debug/references/hypothesis-experiments.md b/skills/debug/references/hypothesis-experiments.md new file mode 100644 index 0000000..b8a6dcb --- /dev/null +++ b/skills/debug/references/hypothesis-experiments.md @@ -0,0 +1,71 @@ +# Hypothesis experiments + +Read before hypothesis testing. Use **hypothetico-deductive reasoning** to distinguish mechanisms. A location, correlation or familiar-looking bug is a lead. A hypothesis explains how a trigger produces the observed failure. + +## Keep a causal record + +Record observations separately from interpretations. Keep plausible alternatives grounded in the failing path. Rank them using evidence, likelihood and the cost of discriminating them. Inventing alternatives to reach a fixed count adds noise. Test one active prediction while preserving its strongest competitors. + +Use the temporary Markdown causal record as the investigation's reference point. Give it a unique name such as `debug-.md`. Record the relevant source revision or contents, environment and original signal once, then append experiments using the fields below. Maintain one short current-state section with the supported account, outstanding alternatives, owned temporary or repair edits, evidence paths, blockers and next step. Update that section in place while preserving experiment history. On resumption, a changed source or environment may invalidate earlier results. + +```text +Observation and intended contract: +Active mechanism and evidence: +Credible alternatives: +Prediction if true: +Falsifier or competing prediction: +Experiment, changed condition and controls: +Actual result and evidence location: +Implication: supported, rejected or inconclusive +Next discriminating step: +``` + +Choose the least costly safe experiment that separates alternatives. Prefer an invariant observation, matched input, controlled configuration, boundary probe or existing detector over a speculative repair. Change one material condition at a time. When interacting conditions are plausible, compare controlled combinations rather than assuming independent causes. + +A valid negative result requires that the experiment reached the relevant path and could expose the predicted effect. Setup failure, an unrelated exception and absent telemetry are inconclusive. A symptom disappearing can reflect masking, a bypassed path, reset state or perturbed timing. Predict an intermediate causal observation as well as the final symptom. A safe A/B comparison or reversal can distinguish these explanations. + +## Worked example, distinguish duplicate mechanisms + +One queue event creates two invoices. The intended contract is one invoice per event. Three credible mechanisms are duplicate delivery without idempotency, duplicate handler registration, and a check-then-insert race. + +```text +H1: Two deliveries each run one handler. +H2: One delivery runs two registered handlers. +H3: Concurrent consumers both observe no invoice before inserting. + +Experiment 1: + Correlate event, delivery, registration and transaction identities. + Result: one delivery runs two registrations sequentially. + Implication: H2 supported. This execution does not require H1 or H3. + +Experiment 2: + Disable only the second registration in a disposable local run. + Predict: one handler execution and one invoice for the same event. + Falsifier: two invoices remain with one handler execution. +``` + +If the second prediction holds, trace why registration occurs twice and which owner should register once. Removing the duplicate registration is a candidate causal repair. Deduplicating displayed invoices or increasing a delivery timeout is unsupported by these observations. + +If Experiment 1 instead reveals two overlapping transactions, test H3 by forcing both reads before either insert through the existing local harness. Duplicate delivery can be a legitimate trigger while missing atomicity is the defect. Account for the interaction rather than declaring that only one factor can be causal. + +## Reset a contradicted premise + +When attempts repeatedly fail under one premise or expose new coupling, stop adding repair edits. Summarise the actual attempts, name their shared premise and recheck the oracle, controls and intended contract. Design the next experiment to reject that premise. Consider hidden state, an unobserved writer, an incorrect comparator, interacting causes or a genuine architectural constraint. An attempt count alone cannot establish architectural failure. + +```text +Failed attempts: changing lock duration and moving the lock did not stop loss. +Shared premise: every writer uses this lock. +New experiment: correlate every write with its writer and lock identity. +Observed: a second writer bypasses that owner. +Next question: must these writers share one object, or are their states independent? +``` + +The next repair can correct ownership or remove unnecessary sharing. Another lock at the already protected site preserves the rejected premise. Ask the user when a remedy changes scope or the intended contract. Continue authorised experiments without an automatic discussion gate after a fixed number of attempts. + +## Transfer a supported repair + +Give `implement` the causal record and obligations needed to deliver the repair. Ensure the record includes the original signal and reduced case, the causal chain from trigger through violated invariant to symptom, decisive experiments, rejected alternatives, proposed repair boundary and verification limits. Preserve the distinction between an input that exposes the bug and the erroneous handling to change. + +Prefer removing the responsible redundant operation or correcting the canonical rule. A retry, guard, fallback, cache or wrapper needs a specific causal and contractual reason. Its small diff alone does not make it the minimal repair. Additional validation should protect a distinct reachable boundary, not repeat the same internal check everywhere. + +Require the original scenario and relevant causal observation to change as predicted. A reduced test can miss interactions in the full scenario. If a repair fails that gate, preserve the result, undo its owned repair edits and return to investigation. Preserve pre-existing work and independently valid evidence or regression protection. A blocked original-scenario check leaves repair verification incomplete. diff --git a/skills/debug/references/investigation-and-patterns.md b/skills/debug/references/investigation-and-patterns.md new file mode 100644 index 0000000..0fbfb6f --- /dev/null +++ b/skills/debug/references/investigation-and-patterns.md @@ -0,0 +1,86 @@ +# Investigation and pattern analysis + +Read during the first two phases. Use the examples to recognise a useful signal, trace the origin of bad state and select a credible comparator. Examples are illustrative, not observations from the current task. + +## Build an exact oracle + +An **oracle** classifies the reported failure, a pass or an inconclusive run. Choose the supported entry that reaches the defect. Reuse a focused test, CLI, HTTP request, UI flow, replay or benchmark. A temporary reproduction harness is investigation equipment. Retained tests belong to the implementation handoff. + +Assert the user's actual symptom. For an export that drops its final row, assert the exact rows and order against an independent expected result. Exit zero and a non-empty file cannot catch that defect. A missing output directory is a different failure and makes the experiment inconclusive. + +Tighten a slow or noisy loop by reducing unrelated setup and controlling relevant state. Preserve the conditions that make the original failure representative. Before clearing caches, resetting data or changing versions, preserve the failing state and effective configuration. A reset can remove both the symptom and the evidence. + +When local reproduction is unavailable, examine the supplied capture's provenance, version, input, correlation identity, completeness and source mapping. Identify the actual transition it records. A complete trace of an invalid value and its producer can distinguish causes. An isolated crash frame or sampled hotspot usually cannot. Seek the smallest missing observation. Absence of reproduction does not establish absence of the defect. + +## Trace the origin and isolate boundaries + +Start at the observed wrong value, effect or decision. Follow producers, callers, prior state and controlling conditions backwards until the last valid and first invalid states are adjacent. For asynchronous work, follow event and job identities as well as stacks. Identify the responsible operation and the conditions that made it violate the intended contract. + +For a path crossing components, correlate one request or datum and inspect the relevant input and output invariants. Walk a short path in order. For a large path, use trustworthy midpoint observations to retain the failing half. Missing, sampled or uncorrelated records leave a gap. Localising one component does not explain its internal cause. + +Choose probes for the active uncertainty, rather than collecting undirected data. + +| Question | Useful observation | +| ----------------------------------------- | -------------------------------------------------------------- | +| Where did this value become invalid? | Conditional breakpoint, watchpoint or targeted data-flow trace | +| Which caller supplied it? | Relevant stack, event identity or producer trace | +| Where did configuration stop propagating? | Effective value or presence at adjacent boundaries | +| Which resource accounts for the delay? | Matching profiler, wait trace or resource counter | + +Prefer existing telemetry and debugger facilities. Add the fewest temporary probes needed. Give owned probes a searchable tag and capture only discriminating fields. Use presence or a redacted identifier for secrets. Check whether logging, pauses or profiling changes the signal. Remove probes after the observation or record a deliberate diagnostic retention within scope. + +## Compare the complete relevant pattern + +Choose a working execution or implementation that promises the same property. Hold shared conditions stable and list differences in input, state, configuration, dependency version, lifecycle, ordering and code. Read the entire relevant pattern, including setup and teardown, before adapting it. Account for intentional differences. Both examples can share a defect, and apparent working behaviour may merely avoid its trigger. + +Use these patterns to generate questions, not to choose a repair without evidence. + +| Failure pattern | Investigate | Tempting symptom patch | +| ------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------ | +| Wrong results after a cache hit | Identity dimensions in the key, invalidation and stale state | Filter the final response or clear every cache | +| Duplicate side effects | Delivery identity, registrations, retry ownership and atomicity | Add another timeout or suppress duplicate output | +| Failure after restart | Persisted schema, migration and effective configuration | Delete all saved state | +| Incorrect output only in a full suite | Setup lifetime, test order and shared files or globals | Retry the suite | +| Old values after an update | Snapshot ownership, closure capture and invalidation | Refresh every consumer | +| Cost grows with input size | Repeated work, fan-out, queues and the actual limiter | Add caching or concurrency immediately | + +After demonstrating a mechanism, inspect sibling occurrences within the affected capability. Verify that each has the same contract and triggering conditions. Similar syntax alone does not establish the same defect or justify a repository-wide sweep. + +## Worked example, trace before adding a guard + +The contract requires each tenant to receive its own search results. Searching for the same phrase first as tenant A and then as tenant B returns A's results to B. Searching as B alone works. + +```text +Original signal: A searches q, then B searches q, in one fresh process. +Expected: A gets A's rows, B gets B's rows. +Observed: both receive A's rows. + +Matched checkpoints: + HTTP identity A / B correct + Parsed tenant A / B correct + Cache lookup key q / q first lost distinction + Repository query A on miss, no query for B downstream consequence + +Alternatives: + Parser loses tenant identity. + SQL omits the tenant predicate. + Cache key omits tenant identity. +``` + +Compare the cached and uncached paths, including their callers. The parser observation excludes one candidate. Execute the repository path for both tenants to test the SQL alternative. Probe the cache by holding the query constant and varying tenant identity. Predict both key separation and correct returned rows. A response filter would hide the visible symptom without restoring correct cache ownership. + +The minimal repair may extend the existing key or remove an unnecessary cache. Choose between them using the supported performance and sharing contracts. This is a decision for the implementation handoff after mechanism confirmation. + +## Worked example, lifecycle before filesystem retries + +A test writes into the source tree instead of its temporary workspace. The failing operation receives an empty directory. Its caller forwards that value from a fixture accessed before setup. The working test reads the fixture after setup. + +```text +Wrong file location + <- filesystem uses current directory for an empty path + <- workspace operation receives an empty fixture field + <- test captures the field during module initialisation + <- setup assigns the temporary directory later +``` + +Observe the fixture value and lifecycle at both reads. The first invalid transition is premature capture, not the filesystem failure. Predict that reading the existing fixture at the correct lifecycle point changes both the argument and output location. Consider deletion of the early copied field before adding getters, retries or validators across every layer. A boundary check earns its place only if a distinct supported caller can still violate that contract. diff --git a/skills/debug/references/nondeterministic-concurrent.md b/skills/debug/references/nondeterministic-concurrent.md new file mode 100644 index 0000000..30a1b33 --- /dev/null +++ b/skills/debug/references/nondeterministic-concurrent.md @@ -0,0 +1,59 @@ +# Nondeterministic and concurrent faults + +Read as soon as the signal depends on timing, order, randomness, load or shared state. Seek a replayable failing execution or a controlled failure rate. One passing retry does not verify a repair. Examples are illustrative. + +## Measure and partition + +Repeat the original trigger and record failures per attempts. Preserve the seed, test order, clock, state, workload, concurrency and any captured schedule. Use the same controls for comparisons. Choose repetitions sufficient for the claim instead of adopting a universal failure-rate threshold. + +Vary the likely dimension that distinguishes current hypotheses. + +| Suspected dependence | Discriminating experiment | +| ------------------------- | --------------------------------------------------------------------- | +| Random input | Replay the seed or sweep a bounded input family | +| Test order | Run suspect sequences from clean state, then remove sequence elements | +| Shared mutable state | Correlate readers and writers, force the suspected interleaving | +| Completion ordering | Observe the producer's actual completion and committed result | +| Time | Control the clock and the relevant deadline through existing tooling | +| Load or resource pressure | Hold workload shape constant and vary the suspected pressure | + +Stress and injected delays can amplify a failure enough to capture it. Preserve the resulting invariant violation or schedule. Logging, debugger pauses and reduced parallelism can hide the original timing. Record probe effects and verify under the original controls too. + +A race detector identifies the fault classes and paths it observes. A clean run does not exclude logical event-order faults or every schedule. Prefer repository-supported tooling and account for its overhead. + +## Worked example, lost updates + +Two workers maintain independent progress counters through one JSON state file. Both read the file, update their own field and write the whole object. The contract requires both counters to survive concurrent completion. + +```text +Initial state: {"a": 0, "b": 0} +Forced schedule: + A reads {"a": 0, "b": 0} + B reads {"a": 0, "b": 0} + A writes {"a": 1, "b": 0} + B writes {"a": 0, "b": 1} +Observed: A's progress disappears. +``` + +Use a barrier in the existing local harness to expose this schedule. Compare it with sequential completion, then trace every writer. Longer sleeps can change the likelihood without removing the read-modify-write race. + +Determine whether the product needs one canonical object. If the counters are independent facts, separate owned state can remove shared mutation and locking work. If a canonical object is a real invariant, the repair needs structural atomicity or synchronisation. Pass this requirement and the preserved schedule to `implement`. Verify both the controlled execution and repeated original workload, with failure counts and uncertainty. + +## Worked example, readiness or an incorrect lifecycle + +A test sometimes reads an empty output array after waiting 50 ms. Observe the job's completion event, the committed output and their order. + +```text +H1: The test reads before valid completion. +H2: The job announces completion before committing its output. + +Observe output at the completion event: + committed output is present -> supports H1 + event precedes commit -> supports H2 +``` + +For H1, use an existing completion promise, event or bounded condition wait. Observe fresh state and report a deadline failure. For H2, waiting longer hides a broken lifecycle contract. Investigate the completion owner instead. Tests of real debounce or expiry intervals need controlled time and their intended timing assertions, rather than an unrelated readiness poll. + +## Order-dependent pollution + +A test passing alone can still fail after another test leaves a listener, file, port or global behind. Preserve the failing order. Reduce the sequence against the exact failure, resetting initial state consistently between trials. Running each test individually cannot exclude a multi-test interaction. Locate the producer of the residual state and compare setup and teardown with a working owner. diff --git a/skills/debug/references/performance-resource.md b/skills/debug/references/performance-resource.md new file mode 100644 index 0000000..327a10a --- /dev/null +++ b/skills/debug/references/performance-resource.md @@ -0,0 +1,61 @@ +# Performance and resource faults + +Read as soon as the symptom concerns latency, throughput, CPU, memory, I/O, contention, queueing, leakage, exhaustion or cost. Connect the responsible work or wait to the user's measured regression. Examples are illustrative. + +## Establish comparable measurements + +Define the intended threshold or trustworthy baseline, full workload, input scale and shape, environment, warm-up, cache state, concurrency, measurement interval and repetitions. Inspect the harness. Confirm that it counts errors, validates correct output and includes actual completed work in the measured region. + +A fast rejection, unconsumed generator, unawaited promise or cache bypass can produce a plausible number for work that never happened. A small fixture can select a different database plan or avoid the production pressure. Preserve these fidelity limits. + +Compare repeated runs under equivalent conditions. Interleave baseline and candidate when drift matters. Report the relevant distribution and variation, not only a mean. A difference within noise is inconclusive. Separate diagnostic profiles from comparable timing runs when profiler overhead matters. + +## Find the limiter + +Use the **USE method**, utilisation, saturation and errors, to triage relevant resources. Then select evidence that answers the active hypothesis. + +| Suspected cost | Useful evidence | +| ----------------------------------- | ------------------------------------------------------------------- | +| CPU work | Call-path profile under the representative workload | +| Waiting, queueing or contention | Off-CPU trace, queue depth, lock or resource counters | +| Memory growth | Allocation profile and retaining paths across equivalent lifecycles | +| Database work | Actual query plan, cardinalities, I/O, waits and query counts | +| Version or configuration regression | Matched benchmark or trustworthy change bisection | + +A hotspot identifies where sampled work occurs. It does not automatically explain end-to-end latency. A caller can generate unnecessary work, a load generator can saturate before the server, and a fast CPU path can spend most wall time waiting elsewhere. Connect the proposed mechanism to both a low-level observation and the original user-visible measure. + +Before adding caches, concurrency or cheaper machinery, test whether the work is needed, repeated unnecessarily or performed too often. Removing unused work is the first candidate when the supported contract permits it. Preserve output, ordering and required timing. + +## Worked example, delete the unused pass + +An export is slow for large inputs. Its contract requires one complete ordered CSV. A profile locates repeated serialisation. + +```text +Baseline workload: same records, release build, same cache and concurrency. +Observed: formatRows(records) runs twice. +Data flow: first result is discarded, second is written. + +Hypothesis: the unused first pass causes the added CPU work and latency. +Experiment: remove only that pass in a disposable local run. +Predict: one serialisation, identical CSV, reduced end-to-end latency. +Falsifier: one serialisation remains slow because another limiter dominates. +``` + +Trace callers and effects to establish that the first pass owns no required work. Count serialisations and validate the full CSV, then measure complete unprofiled exports under the original controls. If work falls but latency does not, preserve that result and investigate the remaining limiter. Do not report the regression fixed from a faster helper alone. Pass the causal deletion and verification obligations to `implement` when supported. + +## Worked example, retained objects or a leak + +Opening and closing a panel repeatedly increases memory. Compare snapshots at the same lifecycle point after the same cycles and collection conditions. Follow growing objects' retaining paths to their owners. + +```text +Observation: detached panel nodes remain after close. +Retaining path: global event listener -> closure -> panel. +Comparator: another panel unregisters its listener during teardown. +Prediction: matching ownership and teardown removes that retaining path. +``` + +Growth alone can be caching or delayed collection. Console inspection can itself retain objects, and a snapshot can perturb collection. Test the lifecycle and retaining path, then repeat the original cycles and user-visible resource observation. One smaller snapshot at a different stage does not verify a repair. + +## Verify the actual regression + +After the causal repair, rerun the same workload and controls. Check both the relevant causal metric and the end-to-end outcome, with functional correctness and errors. Report repetitions, distribution, remaining variation and fidelity gaps. If an environment or capture boundary prevents the original comparison, verification remains incomplete. diff --git a/skills/debug/references/reduction-and-bisection.md b/skills/debug/references/reduction-and-bisection.md new file mode 100644 index 0000000..9851bb2 --- /dev/null +++ b/skills/debug/references/reduction-and-bisection.md @@ -0,0 +1,48 @@ +# Reduction and bisection + +Read when a trigger is large or the failure appeared between ordered states. Both techniques narrow the search. Neither establishes a causal mechanism by itself. Examples are illustrative. + +## Delta debugging + +Freeze an oracle that recognises the exact failure, a pass and an invalid or unresolved candidate. Preserve the original input, seed, ordering and environment. Remove a coherent partition, run the unchanged oracle and retain the removal only when the same failure remains. Try complementary removals and finer partitions when coarse removal fails. Preserve dependencies and syntax needed for a valid candidate. + +Stop when no remaining unit can be removed at the selected granularity without losing the failure, or when the bounded case is more useful to investigate than further reduction. State the reduction boundary. **1-minimality** means no single remaining element can be removed. It does not mean globally smallest. + +### Worked example, two interacting rows + +An import of 10,000 rows rejects two records with the same identifier. It should report the duplicate and leave storage unchanged. + +```text +Oracle: exact duplicate-ID error and unchanged storage. +Unresolved: invalid CSV, missing headers or a different exception. + +Remove the second half: passes. +Remove the first half: passes. +Conclusion: neither half alone carries the failure. +Next: remove smaller complementary chunks while retaining cross-half pairs. +Reduced case: header plus two distant rows with the same identifier. +``` + +Both rows are load-bearing together. Do not classify the original failure as unreproducible because each half passes. An oracle that accepts any exception could instead reduce to a malformed header and investigate the wrong defect. Use the smaller case to form hypotheses, then verify a repair against the original full import. + +## Change bisection + +Use bisection when one property is reliably absent at a good endpoint and present at a bad endpoint. States can be revisions, versions, configurations or ordered inputs. Confirm both endpoints with the same classifier before choosing midpoints. A noisy classifier needs the nondeterministic method before ordinary bisection is trustworthy. + +Test the midpoint, record its exact state and verdict, retain the interval containing the transition and repeat. Keep toolchains and dependencies comparable. Use an isolated worktree or disposable copy for historical states when the current checkout contains work to preserve. Exit the owned bisect session when finished and retain its log. + +For `git bisect run`, exit `0` means good, `1` through `127` except `125` mean bad, and `125` means untestable. Translate setup failures explicitly. A build failure unrelated to the symptom is not evidence of the target regression. + +### Worked example, separate setup from row loss + +```text +Known good: revision A exports all three fixture rows in order. +Known bad: revision Z exports only two. +Classifier: build the revision, export the same fixture, compare exact rows. + +Midpoint M cannot build with the available toolchain -> untestable. +Midpoint P builds and loses the last row -> bad. +Search result: Q introduced row loss, or Q/R remain candidates after skips. +``` + +Inspect the semantic change and test its predicted effect on iteration or flushing. A first bad revision is localisation evidence. Skipped neighbours may leave several candidates. Environment drift, interaction with other changes, or a property that fails, recovers and fails again can invalidate a simple first-transition interpretation. Report that limit rather than invent a unique cause. diff --git a/skills/define-product/SKILL.md b/skills/define-product/SKILL.md index fe09898..440143a 100644 --- a/skills/define-product/SKILL.md +++ b/skills/define-product/SKILL.md @@ -1,63 +1,26 @@ --- name: define-product -description: Defines a breadth-first product and system requirements foundation. Use when externalising a new product idea or deliberately revising PRODUCT.md. -metadata: - type: performer -disable-model-invocation: true +description: Define and document a whole software product when an idea or existing product needs discovery and definition. --- -# Define Product +# Define product -Turns a product idea or existing system into one confirmed `PRODUCT.md` that supplies product intent and system-wide requirements to later feature specifications. +Produce a confirmed `PRODUCT.md` with whole-product intent, system-wide requirements and a high-level feature index. Use **discovery** and **story mapping** to establish breadth before deepening individual features. -## Process +## Inputs -### 1. Establish the evidence boundary +Take the idea, product or requested revision from the request and its supplied context. Read relevant project guidance and linked authorities. For an existing product, inspect representative journeys and contracts. Preserve unrelated confirmed content, identifiers and specification links. -Locate the project root; read its repository guidance and check root `PRODUCT.md`, `GLOSSARY.md`, applicable ADRs and research. For an existing system, also inspect the smallest representative public contracts, entry points, data, tests, configuration, and operational evidence needed to understand the product. Record absent foundation files as absent evidence rather than skipping the check. +## Method -Treat the user as authority for intended direction, repository and runtime evidence as evidence of current behaviour, and cited external sources as authority only for the claims they establish. +1. **Prepare discovery.** Read [discovery guidance](references/discovery.md) and [the product template](assets/product-template.md) before mapping the decision tree. Treat the starting idea as a hypothesis to explore, not a complete feature list. Resolve discoverable facts through inspection or [$research](../research/SKILL.md). +2. **Elicit the whole product.** Invoke [$elicit-with-context](../elicit-with-context/SKILL.md) for product needs, journeys, missing features and shared constraints, using the discovery guidance. Keep detailed feature rules and internal implementation for later stages. +3. **Build the feature index.** Give each feature a stable ID, name, brief outcome and boundary, and specification field. Leave new specification fields blank. Connect features to journeys and goals. Account for every agreed need through a feature, shared requirement or explicit exclusion, and justify every indexed feature. Preserve existing IDs and use `FEAT-*` for new entries unless a convention already exists. +4. **Check the foundation.** Check journey coverage, the feature index and shared requirements. Record the scope and consequence of detail reserved for feature specification. Supply this complete foundation to the active dialogue for confirmation. +5. **Write and check.** Invoke [$write-prose](../write-prose/SKILL.md) with the confirmed foundation, evidence and template. Write root `PRODUCT.md`. Distinguish confirmed intent, observed facts and unresolved assumptions. Link glossary, rationale and research in their authoritative homes. Re-read for fidelity, feature coverage, consistent identifiers and intact specification links. -Separate confirmed target requirements, observed current behaviour, assumptions, and unknowns before questioning. Preserve unrelated confirmed content and local conventions when revising the foundation. When the current product is difficult to reconstruct, load [Discovery Techniques](references/DISCOVERY.md). The evidence, provenance, contradictions, and unresolved decisions are explicit. +## Finish -### 2. Elicit the breadth-first foundation +Return the document path, coverage checked and material limitations. Stop after product definition and context maintenance owned by invoked skills. -Invoke `$elicit-with-context` for material user-held information and decisions throughout steps 2–4. Reuse compatible confirmed answers and derive discoverable facts before questioning. Invoke `$research` when a material external claim could change a requirement and its evidence must persist; link the resulting report rather than copying it. - -Establish the foundation from problem to design inputs: - -1. authority and executive orientation; -2. purpose, problem, vision, users, actors, stakeholders, and needs; -3. value, product and business goals, observable success measures, scope, boundaries, and non-goals; -4. current situation and confirmed target direction when an existing system makes the distinction material; -5. end-to-end journeys from entry through value, recovery, support, and completion or exit; -6. a whole-product functional capability catalogue; and -7. system-wide quality, context, interface, data, integration, security, privacy, safety, compliance, technology, platform, operational, and lifecycle requirements. - -Map the whole product before deepening any capability or technical concern. Omit a foundation concern only after establishing that it is immaterial. Record commercial or market detail only when it changes requirements. The product surface and every material system-wide design input are visible without becoming a feature specification. - -### 3. Shape traceable requirements - -Group capabilities under natural product areas. Give each a stable `CAP-*` identifier and a mini-brief containing its actors and value, high-level externally observable responsibility, meaningful inclusions and exclusions, and source need, goal, journey, obligation, or evidence. Do not add routine delivery or current-state metadata. Leave user stories, detailed functional and non-functional feature requirements, business rules, states, scenarios, examples, and acceptance criteria to later feature specifications. - -Give every material technical requirement a stable semantic identifier, such as `QUAL-*`, `INT-*`, `DATA-*`, `SEC-*`, `TECH-*`, or `OPS-*`. State the requirement, rationale and source, affected scope, and observable measure or later-verifiable response when applicable. Distinguish hard constraints from preferences. Record mandated external contracts, platforms, runtimes, database families or drivers, hosting limits, and standards as constraints; do not select internal boundaries, components, schemas, endpoints, payloads, algorithms, frameworks, deployment topology, controls, or other implementation mechanisms merely to fill the document. Later feature specifications own the feature-specific technical how, and ADRs own qualifying architecture decisions and rationale. - -Record assumptions, dependencies, constraints, risks, and open questions distinctly. A non-blocking unresolved item states its evidence, consequence if wrong, affected requirements, owner, and resolution trigger. Do not confirm the foundation while an unresolved item makes the product boundary unsafe or prevents responsible feature specification. - -### 4. Confirm readiness - -Walk every intended user and lifecycle stakeholder across the journeys, capabilities, and applicable technical requirements. Resolve material omissions, duplicates, broken transitions, contradictory ownership, untraceable requirements, hidden feature depth, and requirements that prescribe unconfirmed design. Check that every normative requirement is necessary, feasible enough for this stage, unambiguous at its level, source-traceable, and capable of later verification. - -Invoke `$elicit-with-context` with the proposed foundation, non-blocking unresolved items, and exact document effect. Use its confirmed synthesis as authority for the agreed `PRODUCT.md` write. If coverage changes afterward, resolve the affected foundation again before writing. - -### 5. Write the foundation - -Create or update the single root `PRODUCT.md` using the [Product and System Requirements Template](assets/product-template.md). Keep one authority even when some sections are omitted as immaterial. Preserve unrelated confirmed content and stylistic local structure. Use stable identifiers and direct links so later feature specifications can trace to the foundation without copying it. Assign identifiers to capabilities, material technical requirements, product-level acceptance, and unresolved records that need downstream reference; do not number every narrative section, goal, measure, or journey by default. - -State each fact and requirement once, then link its identifier. Keep journeys, readiness, acceptance, and evidence from restating the catalogue; add no traceability matrix when inline source traces already establish coverage. - -### 6. Verify and stop - -Verify intended direction against the confirmed synthesis, current claims against inspected evidence, terminology against `GLOSSARY.md`, and material external claims against cited research. Check authority, scope, journeys, capability and technical-requirement coverage, identifier uniqueness, source traceability, internal consistency, explicit non-blocking uncertainty, product-level acceptance, and foundation readiness. Confirm the absence of delivery status, priorities, roadmap, releases, tickets, detailed feature acceptance, selected feature implementation, internal architecture inventory, and unsupported precision. - -Report changed files, supporting evidence, verification, non-blocking unresolved items, and limitations. Stop after `PRODUCT.md` and the glossary changes owned by invoked skills are verified. Do not create feature specifications, ADR decisions, work items, scaffolding, implementation, releases, or deployments. +**Done only when** contextual elicitation is complete and the saved document faithfully records its journeys, feature index and system-wide requirements. Report any unmet prerequisite and its dependent work. Leave feature specifications, ticket planning and implementation to subsequent requests. diff --git a/skills/define-product/agents/openai.yaml b/skills/define-product/agents/openai.yaml index 9b960e1..39ea2fd 100644 --- a/skills/define-product/agents/openai.yaml +++ b/skills/define-product/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Define Product' - short_description: 'Define product and system requirements' -policy: - allow_implicit_invocation: false + short_description: 'Discover product scope and high-level features' diff --git a/skills/define-product/assets/product-template.md b/skills/define-product/assets/product-template.md index 7d81795..7984287 100644 --- a/skills/define-product/assets/product-template.md +++ b/skills/define-product/assets/product-template.md @@ -1,119 +1,47 @@ # {Product name} -> **Authority:** This document owns confirmed whole-product intent and system-wide requirements. Feature specifications refine it without silently changing it. + - +## Product overview -## Executive summary +{Problem, intended users, product purpose and distinguishing value. State the whole-product boundary.} -{Orient readers with intended users, problem, product outcome, distinguishing approach, and consequential boundaries or constraints.} +## Users and needs -## Purpose, problem, and vision +{Who encounters the problem, in what context, what they need to achieve and how they do it today. Include relevant accessibility and operational needs. Separate observed evidence from assumptions.} -{Describe the problem, why it matters, the product's purpose, and the positive change sought without prescribing implementation.} +## Goals and success -## Users, actors, stakeholders, and needs +{Desired outcomes and observable success measures. Supply thresholds and measurement context where confirmed.} -- **{Role or group}:** {Context, needs, pain, and desired outcomes.} +## Scope and exclusions -## Value, goals, and success measures +{Included outcomes, external responsibilities and explicit exclusions. Identify deliberately deferred capabilities separately.} -{Record goals with observable measures, baselines, direction or threshold, measurement source, and horizon where known. Include commercial or market position only when it changes requirements.} - -## Scope, boundaries, and non-goals - -### In scope - -- {Included outcome or responsibility.} - -### Non-goals - -- {Durable exclusion and the focus or ownership boundary it preserves.} - -## Current situation and target direction - - - -{Current evidence, target direction, and material gaps.} - -## Key journeys +## Principal journeys ### {Journey name} -**Actors:** {Users, stakeholders, or external systems.} - -{Narrate entry, outcome, major stages, consequential interactions, recovery or support, and completion or exit. Reference capabilities without repeating their mini-briefs or adding feature scenarios.} - -## Functional capabilities - -### {Natural product area} - -#### CAP-01 — {Capability name} - -- **Actors and value:** {Beneficiaries, need, and enabled outcome.} -- **High-level responsibility:** {One coherent statement of externally observable product behaviour.} -- **Boundaries:** {Important inclusions, exclusions, and adjacent capabilities.} -- **Source trace:** {Need, goal, journey, obligation, research, or current evidence.} - - - - - -### {PREFIX}-01 — {Requirement name} - -{One direct normative requirement.} - -- **Source:** {Confirmed or cited rationale and evidence.} -- **Scope:** {Journeys, capabilities, actors, data, interfaces, or environments governed.} - -## Quality requirements - -{Use `QUAL-*` records for material qualities in their operating context.} - -## System context and external interfaces - -{Briefly describe people and external systems, ownership, exchanges, direction, and trust boundaries. Use `INT-*` records for binding interaction, protocol, standard, ownership, and failure expectations without inventing endpoints, payloads, or adapters. Add a context diagram only when it materially clarifies relationships.} - -## Data and information requirements - -{Use `DATA-*` records for material purpose, categories, sources or sinks, ownership, sensitivity, lifecycle, retention, residency, provenance, scale, or transition obligations.} - -## Integrations and external dependencies - -{Use `INT-*` records for external parties or systems, purpose, exchanges, ownership, mandated contracts, support expectations, failure consequences, or substitution constraints. Link the applicable interface records instead of repeating them.} - -## Security, privacy, safety, and compliance - -{Use `SEC-*` records for protection or assurance outcomes, actor or data scope, trust boundaries, audit obligations, applicable instruments and versions, and risk tolerance.} - -## Technology and platform constraints - -{Use `TECH-*` records for mandated or prohibited platforms, runtimes, languages, database families or drivers, hosting, environments, standards, supported clients, licences, or vendors. State hard versus preferred.} - -## Operational and lifecycle requirements - -{Use `OPS-*` records for availability, support, recovery, capacity, observability, audit, deployment restrictions, maintainability, export, archival, continuity, or retirement outcomes.} +{Actor or initiating event, entry, main activities, intended outcome, material failure or refusal, recovery and exit. Reference the features that support the journey. Keep detailed rules for feature specification.} -## Assumptions, dependencies, constraints, risks, and open questions +## Feature index - +| ID | Feature | Brief description | Supports | Specification | +| ------- | ------- | ----------------------------------------- | ----------------- | ------------- | +| FEAT-01 | {Name} | {Beneficiary, outcome and brief boundary} | {Journey or goal} | | -- **Assumption `ASM-01` — {claim}:** {Evidence; consequence if wrong and affected IDs; owner and resolution trigger.} -- **Dependency `DEP-01` — {condition or party}:** {Evidence; consequence and affected IDs; owner and trigger.} -- **Constraint `CON-01` — {limit}:** {Source and rationale; affected scope; change owner or trigger.} -- **Risk `RSK-01` — {uncertainty}:** {Evidence; consequential effect and affected IDs; owner and review trigger.} -- **Open question `OQ-01` — {question}:** {Why non-blocking; consequence and affected IDs; decision owner and trigger.} + -## Product-level acceptance and foundation readiness +## System-wide requirements -### Product-level acceptance +{Group material shared requirements under useful headings. Cover quality, interfaces and integrations, information lifecycle, security and privacy, safety and compliance, technology constraints, operations and retirement. Establish immateriality before omitting a concern.} -- **ACC-01:** {Whole-product journey, system-wide outcome, or conformance obligation that one feature cannot own cleanly.} +- **{Stable requirement ID}:** {Requirement, affected scope, reason or source, and observable measure or response where applicable. Distinguish mandates from preferences.} -### Foundation readiness +## Assumptions, dependencies and risks -{State evidence that the foundation is coherent and safe for downstream feature specification, plus residual limitations. Do not restate the catalogue, self-certify with a checklist, or claim uninspected evidence.} +{For each material item, state evidence, consequence, affected scope and resolution condition. Identify detail deliberately left for feature specification.} -## Evidence and traceability +## Evidence and decisions -{Link supplied or inspected research, current-system evidence, applicable ADRs, and `GLOSSARY.md`. Do not invent dates, roles, or provenance. Do not add a traceability matrix when the identifiers and inline source traces already establish coverage.} +{Precise links to research, observed current behaviour, glossary and existing rationale. Record confirmed product decisions and their reasons here when this document owns them.} diff --git a/skills/define-product/references/DISCOVERY.md b/skills/define-product/references/DISCOVERY.md deleted file mode 100644 index cdfe354..0000000 --- a/skills/define-product/references/DISCOVERY.md +++ /dev/null @@ -1,19 +0,0 @@ -# Discovery Techniques - -Load only the branch needed when direct inspection and ordinary elicitation do not expose the foundation. `$elicit-with-context` owns shared-understanding questioning; `$research` owns durable external evidence; `define-product` retains `PRODUCT.md` and the stopping boundary. - -## Reconstruct an existing product - -Inspect the smallest end-to-end slices that reveal actors, product boundaries, current behaviour, data ownership, external systems, and consequential constraints. Prefer public documentation and contracts, entry points, representative tests, schemas, configuration, and runtime evidence over an implementation inventory. Sample one normal path, one refusal or failure, one recovery path, and one operational or support path where applicable. - -Distinguish shipped behaviour from planned or abandoned code. Treat names, code structure, framework choices, and deployment configuration as evidence of the present system, not durable target requirements. Reconcile contradictory evidence with the user instead of selecting a source silently. Use legacy product or architecture documents as evidence only until their statements are confirmed into the current authority. - -## Expose the whole product - -Walk each intended user from entry through recurring value, consequential interaction, failure or refusal, recovery or support, and completion or exit. Change perspective to customers, operators, administrators, support, external-system owners, affected parties, and regulators when material. Derive natural product areas and capability mini-briefs from those journeys, then check commercial, account, trust, data, integration, operational, and lifecycle surfaces that the main journey may hide. - -Use meaningful alternatives, manual work, and doing nothing to clarify value and boundaries. Invoke `$research` only when external position, regulation, standards, providers, or user evidence could materially change a requirement and the evidence must survive the session. - -## Expose system-wide requirements - -For each journey and capability, ask what must remain true across likely implementations: operating conditions, measurable qualities, external ownership and exchanges, information duties, trust and harm boundaries, mandated technology, provider or organisational constraints, support and recovery, and eventual export, archival, or retirement. Record only material design inputs. Leave the selected internal structure and mechanisms to later feature specification. diff --git a/skills/define-product/references/discovery.md b/skills/define-product/references/discovery.md new file mode 100644 index 0000000..54c1b40 --- /dev/null +++ b/skills/define-product/references/discovery.md @@ -0,0 +1,38 @@ +# Product discovery + +Use these lenses to prepare a broad **story map** before deepening one feature. + +## Find the problem and boundary + +Explore the idea through the problem it solves, who experiences it, concrete situations, current alternatives and the change sought. Challenge a proposed feature that lacks a need. Distinguish confirmed intentions from evidence of demand. Consider whether a simpler product, manual process or no new software could meet the goal. + +Establish users, relevant system actors, accessibility needs, channels and operating conditions. Separate product responsibilities from external systems. Distinguish required constraints from preferences, including commercial limits when they change the product. + +For an existing product, inspect representative entry points, public contracts, tests, data and operations. Reconstruct actual journeys without turning every code structure or old configuration into a target requirement. + +## Walk the whole lifecycle + +Tell each user's journey from its trigger to value and exit. Explore setup and onboarding, recurring use, changes and cancellation, refusal, failure, recovery, support, export and retirement where relevant. Include administrator and system-initiated paths that the main user journey hides. + +Ask what each activity requires the product to do. Group those responsibilities into high-level features. Then walk the map backwards to find features with no purpose and needs with no feature. A feature can support several journeys. A journey can require several features. + +For example, “a place to book rooms” can expose finding availability, booking, changing or cancelling, conflict prevention, room administration and outage recovery. Confirm which belong before diving into booking fields. Authentication and notifications earn entries only when their responsibilities are needed. + +## Probe shared requirements + +Check what must remain true across features and implementations: + +- Qualities in their actual operating context, such as accessibility, availability, responsiveness and scale. +- Data purpose, ownership, sensitivity, retention, deletion, export and residency. +- External exchanges, trust boundaries, provider limits and failure consequences. +- Security, privacy, safety and applicable obligations. +- Mandated platforms, supported clients, hosting and other hard constraints. +- Operations, observability, support, recovery and eventual retirement. + +Turn “fast” or “secure” into the required response or guarantee in a concrete situation. Resolve uncertain factual obligations through evidence. Ask the user to decide intent and trade-offs. + +## Keep depth deliberate + +Product definition establishes the full high-level map. Feature specification settles detailed policies and consequential solution choices for selected features. Record an unresolved detail at the later level only when its alternatives leave the product boundary and high-level requirements coherent. + +For room booking, establish whether fair access is required and recurring bookings belong in scope. Reserve exact duration, advance-booking and cancellation-cutoff rules for feature specification unless a product-wide mandate already fixes them. diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md index 995ca0b..d8c4b95 100644 --- a/skills/elicit-with-context/SKILL.md +++ b/skills/elicit-with-context/SKILL.md @@ -1,15 +1,26 @@ --- name: elicit-with-context -description: Elicits shared understanding while maintaining software-project context. Use when software-project work depends on material user-held information or decisions. -metadata: - type: router -disable-model-invocation: true +description: Elicit confirmed project understanding while maintaining domain context when a bounded software task needs clarification or stress-testing. --- -# Elicit with Context +# Elicit with context -Elicits shared understanding while maintaining project context. +Return confirmed shared understanding while keeping relevant project terminology and qualifying decision rationale current throughout the dialogue. -## Process +## Inputs -Invoke `$elicit` for questioning. Apply `$maintain-ubiquitous-language` throughout so stable project terms stay current. Invoke `$maintain-decision-records` only when its description applies. Return `$elicit`'s confirmed synthesis. +Take the bounded software task from the request or caller handoff. Supply the caller's outcome and authority boundary to the loaded skills. + +## Method + +1. **Load and keep active.** Read and invoke [$elicit](../elicit/SKILL.md) and [$maintain-ubiquitous-language](../maintain-ubiquitous-language/SKILL.md) **before the first question**. Apply both to the incoming context and throughout the dialogue. +2. **Dispatch ADR maintenance.** When an accepted technical or architectural choice may warrant durable rationale, or an existing ADR needs maintenance, read and invoke [$maintain-decision-records](../maintain-decision-records/SKILL.md). Supply the relevant evidence and prior decisions. +3. **Compose one dialogue.** Route the maintainers' unresolved questions through the active `$elicit` dialogue. + +The maintainers own their artefacts. `$elicit` owns questioning and confirmation. + +## Finish + +Return `$elicit`'s confirmed synthesis and the maintainers' reports. + +**Done only when** each invoked skill has fulfilled its contract. Report any unmet gate and dependent work. diff --git a/skills/elicit-with-context/agents/openai.yaml b/skills/elicit-with-context/agents/openai.yaml index 46f2204..9fbd1f2 100644 --- a/skills/elicit-with-context/agents/openai.yaml +++ b/skills/elicit-with-context/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Elicit with Context' - short_description: 'Elicit while maintaining project context' -policy: - allow_implicit_invocation: false + short_description: 'Elicit with continuous glossary and ADR maintenance' diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md index b5a855c..6181eb9 100644 --- a/skills/elicit/SKILL.md +++ b/skills/elicit/SKILL.md @@ -1,37 +1,29 @@ --- name: elicit -description: Elicits material information and decisions one question at a time until shared understanding is confirmed. Use when user-held context, clarification, or choices block a bounded outcome. -metadata: - type: utility -disable-model-invocation: false +description: Resolve material user-held information and decisions when a bounded task needs clarification or stress-testing. --- # Elicit -Builds confirmed shared understanding by resolving a bounded internal **decision tree**, then applying adapted **theoretical saturation**. +Return confirmed shared understanding by relentlessly traversing a bounded **decision tree**. The user owns their information and decisions. The caller owns downstream action. -## Process +A branch is **material** when differing answers could change the outcome, scope, constraints, trade-offs, success conditions, or a consequential choice. Include choices the agent could otherwise guess. Leave routine details within established direction to the caller. -### 1. Establish the basis +## Inputs -Inspect the request, conversation, caller context, and available task-scoped evidence before questioning. Use cheap read-only fact-finding and stable, confidently applicable general knowledge to close discoverable branches. Verify uncertain, contentious, or potentially current knowledge before treating it as fact. Leave material research and every state-changing action to the caller. The intended outcome, caller boundary, and factual basis are explicit. +Take the task, intended outcome and authority boundary from the request or caller handoff. Resolve discoverable facts through task-scoped read-only inspection before dependent questioning. Verify uncertain or changing claims. Current behaviour is evidence, not authority for intended behaviour. Leave substantial research and changes to the caller. -### 2. Maintain the decision tree +## Method -Build and continually recompute an internal, dependency-ordered tree containing only branches whose resolution could materially change the bounded outcome. Cover relevant outcome, scope, terminology, inputs, outputs, prerequisites, dependencies, constraints, flows, exceptions, permissions, risks, trade-offs, and success conditions. Preserve compatible answers; close, discard, or reopen branches as evidence changes; and follow directly consequential issues without expanding into unrelated discovery. Select the highest-impact unresolved branch whose prerequisites are resolved. Keep the tree internal and one active issue explicit. +1. **Map the tree.** Track material branches, dependencies, and their disposition internally: open, resolved by user answer or evidence, explicitly delegated, or excluded by agreed scope. Preserve compatible answers. Assumptions, recommendations, and unanswered questions leave branches open. +2. **Ask one question per turn.** Choose the highest-impact open branch whose prerequisites are settled. Explain what the answer changes. For a real choice, offer materially different viable options and a grounded recommendation. Ask directly for missing information. Leave room for the user's own answer and wait before relying on it. +3. **Challenge and recompute.** After each answer or discovery, stress-test the proposal and affected answers against the goal, facts, alternatives, implications, concrete scenarios, and counterexamples. Directly identify factual errors, contradictions, and choices that undermine the goal. Explain the evidence or conflict before asking the resolving question. Distinguish evidence from inference and legitimate preferences from errors. Respect fixed constraints while surfacing conflicts that make them untenable. Acknowledge and correct your own mistaken interpretation. Reopen affected decisions, add exposed branches, and recompute dependencies before continuing. +4. **Clarify the same decision.** Resolve ambiguity before relying on an answer. When the user asks for explanation or shows confusion, read [question clarification](references/clarification.md) and rephrase without changing the choice. Close clear answers without ceremonial repetition. An informed preference settles a viable choice. A factual contradiction remains unresolved while dependent work requires it. +5. **Traverse to saturation.** Follow answers into dependent branches, then return to unresolved siblings. Use no question quota. An exhausted list, workable outline, or empty set of askable questions is insufficient. Walk the complete outcome and decision interactions through relevant responsibilities, inputs and outputs, defaults, states and transitions, time boundaries, visibility, exceptions, failure and recovery, and success evidence. Reopen consequential gaps and continue until every material branch has a supported disposition and a fresh coverage pass adds or reopens none. +6. **Confirm the whole.** Present a concise, self-contained synthesis of facts, decisions, scope, constraints, consequential implications, delegated choices, and observable success conditions. Ask one question for explicit agreement. Corrections or later evidence reopen affected branches. Repeat traversal and coverage before confirming the revision. Reuse an earlier confirmed synthesis only when it covers the complete outcome and rechecking finds no material gap or change. Agreement to one option does not confirm the whole. -### 3. Ask one question +## Finish -Ask exactly one explicit question per turn in natural language. Explain why an information question matters. Offer suggested answers only when grounded in the established basis. Apply **Design It Twice**: present at least two genuinely distinct viable options, state the material effect of each, and recommend the strongest when the evidence supports a clear winner. Make those options part of the one question; do not append another choice prompt. Leave room for another answer and keep the user as the sole authority over their information and decisions. The active issue receives one explicit response. +Return the confirmed synthesis to the caller. Create no durable artefact or state change. -### 4. Adapt and validate - -Test every response internally against the outcome, established facts, prior answers, implications, contradictions, scenarios, and counterexamples. Surface a challenge only when it could materially change the shared understanding. Close clear answers without ceremonial repetition. For ambiguity, conflict, difficulty, or consequential interpretation, use plain-English paraphrasing, rewording, clearer options and effects, examples, scenarios, or prerequisite questions resolved one at a time. Do not invent an answer or decide for the user. Recompute the tree and reopen every affected branch. The active issue is resolved consistently. - -### 5. Reach theoretical saturation - -Repeat steps 2–4 until every material branch is resolved. Make an adapted theoretical-saturation pass across the tree, implications, scenarios, counterexamples, and conflicts. Walk each material decision through affected actors and authority, defaults and unchanged behaviour, states and transitions, time boundaries, channels, visibility, exceptions, invalidation, and success evidence; open only consequential gaps. Saturation is reached only when the pass adds or reopens no branch whose answer could materially change the shared understanding. The bounded decision tree is saturated. - -### 6. Confirm shared understanding - -Present one concise, self-contained synthesis of the relevant facts, information, decisions, scope, constraints, implications, and observable success conditions. Ask exactly one question for explicit agreement. Only a new response confirming the complete synthesis ends elicitation; selecting an earlier option does not. Treat a correction or rejection as new evidence, reopen every affected branch, and repeat the saturation pass before presenting a revised synthesis. Return only the confirmed synthesis; create no durable artefact and leave mutation, persistence, verification, downstream action, and the caller's stopping boundary to the caller. +**Done only when** every material branch has a supported disposition, a fresh coverage pass opens none, and the user has confirmed the complete synthesis. If a necessary fact or decision is unavailable, report it and the dependent work. Deferral leaves that work unresolved unless the user changes scope or explicitly delegates the choice. diff --git a/skills/elicit/agents/openai.yaml b/skills/elicit/agents/openai.yaml index 24235cb..e7c3669 100644 --- a/skills/elicit/agents/openai.yaml +++ b/skills/elicit/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Elicit' short_description: 'Elicit material information and decisions' -policy: - allow_implicit_invocation: true diff --git a/skills/elicit/references/clarification.md b/skills/elicit/references/clarification.md new file mode 100644 index 0000000..29c91c4 --- /dev/null +++ b/skills/elicit/references/clarification.md @@ -0,0 +1,55 @@ +# Clarify a question + +Help the user understand the pending decision when they ask for an explanation or show confusion. Choose the technique that addresses the misunderstanding, then ask one rephrased question and wait. Keep the same scope, alternatives, and consequences. Rephrasing does not settle the branch. + +## Restore context and purpose + +Say what is already settled, what remains open, and why the answer matters. Avoid repeating the whole interview. + +**Original:** “What is the retention policy?” + +**User:** “Why are you asking that?” + +**Rephrase:** “We agreed to keep the scanned letters. We still need to decide what happens to the paper originals, because scanning alone does not authorise disposal. Should the originals be kept after the scans are checked?” + +## Replace jargon with observable behaviour + +Use the user's established vocabulary and describe what they would see or do. Define an unavoidable technical term once. + +**Original:** “Must revocation invalidate cached copies?” + +**User:** “What does that mean?” + +**Rephrase:** “Someone downloads a letter, then you remove their access. Should they still be able to read the copy already on their device?” + +## Contrast concrete outcomes + +Show how the viable alternatives differ in the same scenario. Give each a fair description. Explain a recommendation separately. Use an analogy only if it preserves the consequential distinction. + +**Original:** “Should a timeout retry the operation?” + +**User:** “I can't picture the difference.” + +**Rephrase:** “You tap ‘Send’, but the app never receives a reply. Sending again may deliver a duplicate. Waiting may leave the message unsent. Which result should the app favour?” + +## Isolate the prerequisite + +If the question assumes something the user has not decided or understood, ask that prerequisite first. Return to the original branch afterward. + +**Original:** “How should public excerpts be anonymised?” + +**User:** “I don't know where to start.” + +**Rephrase:** “First we need to settle whether excerpts may be public at all. May an excerpt be published without the people mentioned agreeing?” + +## Make the conflict tangible + +State the incompatible claims and walk through a counterexample. Challenge the premise without treating the user's preference as a mistake. + +**User:** “Removing names guarantees nobody can identify the people.” + +**Response:** “A letter could still identify someone through their address, job, or family relationships. Removing names alone cannot guarantee anonymity. Would you require agreement before publishing an excerpt?” + +If your interpretation caused the confusion, correct it first: “I read ‘share’ as public posting, but you meant sending privately. Who may receive a private copy?” + +When talking cannot settle the choice, identify the missing evidence or concrete example the caller needs to obtain. Keep the branch and dependent work open rather than repeatedly asking the user to guess. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index ac6fc57..61ae531 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -1,50 +1,29 @@ --- name: implement -description: Implements one ticket or small confirmed software change as a minimal, locally checked, independently reviewed candidate. Use when agreed software work is ready to build locally. -metadata: - type: performer -disable-model-invocation: true +description: Deliver a minimal, independently reviewed code change when the user requests a software implementation or modification. --- # Implement -Turns one confirmed body of software work into the smallest coherent local change with applicable quality evidence and independent review. +Deliver the complete confirmed outcome with the **least justified code and complexity**. Preserve unrelated work. -## Process +## Inputs -### 1. Fix the implementation basis +Use the requested change or ticket and any supplied acceptance criteria. Invoke [$elicit-with-context](../elicit-with-context/SKILL.md) when a material user-held decision remains unresolved. -Inspect the work authority, repository instructions, linked product and technical authorities, current code, tests, relevant contracts, available tools, and complete repository state. State the observable outcome, exclusions, material risks, and completion evidence. Resolve discoverable facts directly. Invoke `$elicit-with-context` only when a material user-held behaviour, contract, architecture, scope, or acceptance decision remains. +## Method -When the work uses or changes a package, framework, SDK, platform, or external API, identify the applicable version and inspect its official documentation, source, or examples. Follow its documented convention unless the work authority, repository instructions, architecture decisions, or a deliberate local convention requires otherwise. Resolve missing or materially conflicting guidance instead of inventing an integration pattern. +1. **Prepare.** Read repository documentation and official documentation for the installed packages and frameworks involved in the change. Follow their recommended APIs and patterns unless an explicit project decision requires a different approach. Load and apply [$modular-design](../modular-design/SKILL.md). +2. **Implement.** Load [$test-design](../test-design/SKILL.md) and follow its applicability decision and method. Implement the confirmed change and simplify locally as it takes shape. When new tests are ineligible, use existing checks and direct verification. +3. **Improve.** Once the change works, invoke [$measure-code-complexity](../measure-code-complexity/SKILL.md) on the changed production files, using the branch base for file selection. Pass its saved report and interpretation to [$code-cleanup](../code-cleanup/SKILL.md) with the fixed candidate and affected capability. Read the returned report file and adjudicate every candidate, including changes in related unchanged files. Resolve preservation gaps before applying accepted transformations. +4. **Verify and review.** Run required repository checks and the complete relevant existing suite. Invoke [$code-review](../code-review/SKILL.md) on the resulting candidate with its behavioural authorities and quality evidence. Read the returned report file. Check its assessment status and coverage before resolving its findings. Refresh an incomplete or stale review before treating the candidate as independently reviewed. -Keep the outcome to one implementation-ready ticket, diagnosed repair, or small confirmed change. Preserve unrelated work. Stop when the work is not sufficiently defined to implement and elicitation cannot resolve it within the requested outcome. +For both cleanup and review, **adjudicate each finding** against the request, actual code and documented constraints. Apply required corrections and proportionate improvements. Reject inapplicable findings with concrete evidence and record each disposition and its reason. For example, a request to add internal validation may be redundant when every supported entry already enforces that invariant at runtime. A preferred style or lower metric alone does not justify a change. Resolve material user-held decisions through `$elicit-with-context`. -### 2. Load the teaching knowledge +After edits, refresh affected checks and remeasure the same selected files. Keep prior reports for caller-owned comparisons. After a material edit, repeat independent review of the revised candidate. -Invoke `$modular-design` against the fixed work. Invoke `$tdd` when the change affects observable behaviour and an existing usable suite can exercise it through a credible seam. Apply their guidance throughout implementation. +## Finish -### 3. Build and check the candidate +Return delivered behaviour, significant structural changes, checks, measurement and review results, finding dispositions and material limitations. -Implement the smallest coherent change that completely satisfies the confirmed outcome. Follow the selected modular constraints and TDD cycles without adding speculative flexibility, unrelated cleanup, or project-wide quality infrastructure outside the agreed work. - -Inspect the complete diff and every in-scope untracked file. Account for each production and test addition, dependency, generated artefact, and measurement-path change. Run applicable repository-required checks. Preserve exact results, unavailable evidence, and residual risks. - -After applicable checks are current, invoke `$measure-code-complexity` with the fixed candidate, comparison base, and implementation authority. Resolve each supported concern by applying an authorised coherent improvement, retaining a supported justification, or invoking `$elicit-with-context` when resolution would change agreed behaviour, contracts, architecture, or scope. Rerun every affected harness and invoke the measurement again after a change. Freeze one complete candidate only when its checks and complexity measurement are current and every trigger is resolved or explicitly retained for handoff. - -### 4. Review and adjudicate - -Invoke `$code-review` on the frozen candidate and its authorities. Validate every Spec and Standards suggestion against the strongest available authority and evidence, then disposition it as: - -- **Required correction:** a confirmed violation, regression, safety defect, or evidence weakness that leaves the change untrustworthy. -- **Proportionate improvement:** a valid in-scope benefit worth its added change and complexity. -- **Rejected finding:** falsified, unsupported, superseded, or outside the confirmed scope. -- **User decision:** resolution would change agreed behaviour, contracts, architecture, or scope, or needs evidence that cannot be obtained safely. - -Apply required corrections and accepted improvements. Invoke `$elicit-with-context` for a user decision. Rerun every affected harness after a candidate or measurement-path change. Freeze and review the complete new candidate after any material change. Continue until every finding has a supported disposition and no applicable correction or accepted improvement remains. - -### 5. Hand off the local result - -Report the delivered behaviour, changed artefacts, applicable TDD and modular-design decisions, exact checks and results, unavailable evidence, residual risks, review scope and results, and every finding disposition. Successful completion requires the agreed behaviour locally, every production addition serving a current purpose, applicable evidence passed or explicitly unavailable, and current Spec and Standards review with no unresolved applicable change. - -Stop without committing, pushing, opening or updating a pull request, changing tracker state, releasing, or deploying. Do not conduct exploratory research, create specifications or tickets, or add unrelated quality infrastructure inside this outcome. +**Done only when** the agreed outcome works, applicable checks are current, every finding has an evidence-backed disposition, and all required corrections and accepted improvements are complete. Report actual blockers precisely. Stop at the local handoff. Commit, publication, tracker updates and deployment require separate instructions. diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml index 5421aeb..a6db89a 100644 --- a/skills/implement/agents/openai.yaml +++ b/skills/implement/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Implement' - short_description: 'Implement and review one local change' -policy: - allow_implicit_invocation: false + short_description: 'Deliver the smallest complete, reviewed code change' diff --git a/skills/maintain-agents/SKILL.md b/skills/maintain-agents/SKILL.md index 423386d..76eb850 100644 --- a/skills/maintain-agents/SKILL.md +++ b/skills/maintain-agents/SKILL.md @@ -1,33 +1,30 @@ --- name: maintain-agents -description: Maintains concise root AGENTS.md instructions. Use when creating the file or adding, refining, or assessing repository-wide agent guidance. -metadata: - type: utility -disable-model-invocation: true +description: Create or update a project's root AGENTS.md when the user or a caller requests project instructions. --- # Maintain AGENTS.md -Uses **Progressive Disclosure** to keep the repository's always-loaded agent guidance relevant to every request. +Keep root `AGENTS.md` lean through **progressive disclosure**. Write short instructional sentences, one concept per bullet. -## Process +## Inputs -### 1. Establish the file +Take the requested instruction change from the request or caller handoff. Locate the project root. Treat explicit user or caller instructions as authority. Ask only about material ambiguity. -Locate the repository root and read its `AGENTS.md` when present. Create it when absent. Ensure this line appears exactly once at the top, replacing or moving equivalent wording: +## Method -```markdown -- When a user correction establishes a reusable repository-wide rule, ask whether to invoke `$maintain-agents` to add it. -``` +1. Read the existing file. For setup, create a missing file with only this default line. Keep it first and present exactly once, replacing equivalent wording: -### 2. Assess the guidance + ```markdown + - When a user correction establishes a durable project-wide instruction needed in every session, ask whether to invoke `$maintain-agents` to add it. + ``` -Recommend an instruction when it is user-confirmed, cannot be inferred reliably from repository evidence, governs the repository as a whole, and materially changes agent behaviour. Treat a composing caller's confirmed instruction as user-confirmed. When an instruction fails a gate, explain the concern and ask for the user's final decision; follow that decision. +2. Apply the requested change with direct instructions. Preserve necessary conditions and exact commands. Update equivalent wording rather than adding duplicates. Preserve unrelated guidance during a targeted edit. +3. For a whole-file tidy, remove repetition and obsolete material while preserving intended behaviour. Ask before a substantive deletion whose intent is uncertain. +4. Follow explicit requests to include task-specific content. Apply the default line's strict reuse test only to proactive suggestions. -### 3. Write the instruction +## Finish -Apply only the requested addition, refinement, or assessment. Use the shortest direct imperative sentence that preserves the required behaviour and conditions. State each policy once; update equivalent wording instead of adding a semantic duplicate. Leave unrelated instructions unchanged. +Return the change or supported no-op and any unresolved ambiguity. Edit only root `AGENTS.md`. -### 4. Verify the result - -Re-read `AGENTS.md`. Confirm the canonical first line, requested outcome, minimal wording, and absence of semantic duplication. Return the change, no-op, or requested advice with any concerns. +**Done only when** rereading confirms the requested effect, short instructions, preserved meaning, no semantic duplicates, and the canonical first line exactly once. diff --git a/skills/maintain-agents/agents/openai.yaml b/skills/maintain-agents/agents/openai.yaml index 2b4bbb9..7b08745 100644 --- a/skills/maintain-agents/agents/openai.yaml +++ b/skills/maintain-agents/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Maintain AGENTS.md' - short_description: 'Write concise repository-wide agent guidance' -policy: - allow_implicit_invocation: false + short_description: 'Create and maintain a lean project AGENTS.md' diff --git a/skills/maintain-decision-records/SKILL.md b/skills/maintain-decision-records/SKILL.md index 101cf9d..915216f 100644 --- a/skills/maintain-decision-records/SKILL.md +++ b/skills/maintain-decision-records/SKILL.md @@ -1,36 +1,26 @@ --- name: maintain-decision-records -description: Maintains rare architecture decision records. Use when an accepted technical or architectural decision may warrant durable rationale. -metadata: - type: utility -disable-model-invocation: true +description: Preserve exceptional technical or architectural rationale when an accepted decision qualifies for an ADR or an existing record needs correction, supersession, or deprecation. --- -# Maintain Decision Records +# Maintain decision records -Preserves the rationale for exceptional accepted technical or architectural decisions in concise Architecture Decision Records. +Preserve exceptional accepted rationale in concise **architecture decision records**, retaining decision history when choices change. -## Process +## Inputs -### 1. Inspect the decision +Take the accepted decision or requested record change from the conversation or caller handoff. Separate documented rationale from inference. Code alone cannot establish why a choice was made. -Inspect the accepted decision, relevant conversation or caller handoff, existing `docs/adr/` records, applicable repository guidance, and only the product, architecture, feature, governance, or implementation evidence needed to establish its owner and rationale. Do not scan unrelated decisions. The candidate decision, alternatives, consequences, existing coverage, and user authority are explicit. +## Method -### 2. Gate the record +1. **Check coverage.** Read relevant existing records and other durable authorities. Reuse existing coverage instead of duplicating it. When correcting or revisiting a recorded decision, read [record lifecycle](references/lifecycle.md) before changing it. +2. **Qualify new records.** Create an ADR only when **all** conditions hold: reversal has meaningful cost, the choice would surprise a future reader without context, viable alternatives created a real trade-off, and no existing durable authority already records it or is its better owner. A routine, unaccepted, or already-owned choice produces no new ADR. +3. **Establish agreement.** Require explicit user agreement to preserve the qualifying rationale. Reuse agreement from the conversation or caller handoff. Acceptance of the choice alone is insufficient. If agreement is missing, ask one direct question within the active dialogue and wait before writing. A refusal produces an explained no-record outcome. +4. **Write the content.** Invoke [$write-prose](../write-prose/SKILL.md) for ADR content, supplying the accepted decision, evidence, future-reader audience, and template or existing structure. For a new record, use [the ADR template](assets/adr-template.md) and create `docs/adr/` lazily. Use `NNNN-decision-shaped-slug.md`, starting at `0001` or one above the largest existing four-digit prefix. Preserve existing identifiers and never overwrite a sibling. Keep sections concise and record only supported rationale, necessary alternatives, material consequences, and useful reconsideration conditions. +5. **Check the result.** Read changed records back against the accepted choice, evidence, eligibility, and agreement. Verify numbering, status, and lifecycle links. Preserve unrelated records and caller-owned artefacts. -Create an ADR only when the accepted technical or architectural decision passes every gate: +## Finish -- changing it later has meaningful cost; -- a future reader would find it surprising without context; -- viable alternatives created a genuine trade-off; and -- no existing durable authority already records the decision or is its better owner, including `PRODUCT.md`, a feature document, or a dedicated governance record. +Return created or changed paths, or why no ADR was warranted, and any missing evidence, agreement, or failed write. -Require the user's explicit agreement to preserve the rationale durably. Agreement recorded in the relevant conversation or caller handoff satisfies this gate without another prompt. When every other gate passes but agreement is absent, ask the user one direct question. A decision that misses a gate, lacks agreement, or is routine or discoverable produces no ADR. - -### 3. Write the ADR - -Create `docs/adr/` lazily and write the next record from the [ADR template](assets/adr-template.md). Name it `NNNN-decision-shaped-slug.md`: use `0001` when no sibling matches `NNNN-*.md`; otherwise add one to the largest four-digit prefix. Keep exactly three substantive sections in order: `Decision`, `Context`, and `Consequences`. Record the accepted choice, why it was needed, only the rejected or constrained alternatives necessary to explain its trade-offs, and its material consequences. - -### 4. Verify the result - -Re-read the ADR against the accepted decision, every gate, the user's agreement, and relevant evidence. Return the created file or why no ADR was warranted. Change no caller-owned product, architecture, feature, code, external state, or verification outcome. +**Done only when** the qualifying agreed rationale or authorised lifecycle change is written and checked, or a supported no-record outcome is reported. Missing prerequisites leave dependent maintenance incomplete. diff --git a/skills/maintain-decision-records/agents/openai.yaml b/skills/maintain-decision-records/agents/openai.yaml index 29d96ca..aa6ff08 100644 --- a/skills/maintain-decision-records/agents/openai.yaml +++ b/skills/maintain-decision-records/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Maintain Decision Records' - short_description: 'Maintain rare architecture decisions' -policy: - allow_implicit_invocation: false + short_description: 'Preserve exceptional rationale and ADR history' diff --git a/skills/maintain-decision-records/assets/adr-template.md b/skills/maintain-decision-records/assets/adr-template.md index bf22119..40e7106 100644 --- a/skills/maintain-decision-records/assets/adr-template.md +++ b/skills/maintain-decision-records/assets/adr-template.md @@ -1,13 +1,15 @@ -# {Decision-shaped title} +# {Decision title} -## Decision - -{State what was decided and the essential reason first.} +Status: Accepted ## Context -{Explain why the decision was needed and only the rejected or constrained alternatives necessary to understand its trade-offs.} +{Problem, constraints, and necessary alternatives.} + +## Decision + +{Accepted choice and essential reason.} ## Consequences -{State the significant consequences, trade-offs, and conditions that could trigger reconsideration.} +{Material benefits, costs, and reconsideration conditions.} diff --git a/skills/maintain-decision-records/references/lifecycle.md b/skills/maintain-decision-records/references/lifecycle.md new file mode 100644 index 0000000..2fc403e --- /dev/null +++ b/skills/maintain-decision-records/references/lifecycle.md @@ -0,0 +1,11 @@ +# Record lifecycle + +Read this when correcting or revisiting an existing ADR. Reuse the new-record eligibility and agreement rules from [the skill](../SKILL.md). + +- **Correction.** Correct wording, links, or evidenced recording errors in place. Preserve the historical choice and rationale. Resolve unclear historical intent before changing its meaning. +- **Supersession.** When an accepted replacement qualifies and preservation is agreed, create the next numbered ADR. Explain the changed context and link the predecessor in the successor. Mark the predecessor `Status: Superseded by [ADR NNNN](NNNN-slug.md)`, linking to the successor. Retain its historical body and identifier. +- **Deprecation.** When confirmed intent establishes that a decision ceases to apply without an ADR successor, mark it `Status: Deprecated` and add the supported reason and any replacement authority. Retain its historical body. A proposal or contradictory current code does not establish deprecation. + +Reuse prior preservation agreement for faithful corrections and confirmed lifecycle metadata updates. A new successor still needs agreement to preserve its new rationale. If a proposed successor fails the new-record gate, report why no ADR was created. Resolve whether the old decision still applies before changing its status. + +Read both records back after supersession. Check reciprocal links, actual targets, status, and preserved historical rationale. On repeated invocation, reuse the existing successor instead of creating another record. diff --git a/skills/maintain-ubiquitous-language/SKILL.md b/skills/maintain-ubiquitous-language/SKILL.md index f5f2b7d..3d3a827 100644 --- a/skills/maintain-ubiquitous-language/SKILL.md +++ b/skills/maintain-ubiquitous-language/SKILL.md @@ -1,27 +1,29 @@ --- name: maintain-ubiquitous-language -description: Maintains project-specific language in GLOSSARY.md. Use when project terminology must be added, changed, challenged, renamed, deprecated, or reconciled. -metadata: - type: utility -disable-model-invocation: true +description: Sharpen and maintain ubiquitous language when project terminology is introduced, ambiguous, conflicting, renamed, or deprecated. --- -# Maintain Ubiquitous Language +# Maintain ubiquitous language -Applies **Ubiquitous Language** by keeping project-specific terminology consistent in one root `GLOSSARY.md` glossary. +Actively sharpen **DDD ubiquitous language** and keep one root `GLOSSARY.md` current throughout the conversation. Capture each resolved meaning immediately. -## Process +## Inputs -### 1. Inspect the language +Take affected terms and their intended meanings from the conversation or caller handoff. Read root `GLOSSARY.md` and relevant project evidence. A clear, stable supplied meaning is resolved. Confirmed intended meaning governs an intended change. Current behaviour is evidence, not authority for intent. -Inspect the relevant conversation or caller handoff, root `GLOSSARY.md`, applicable repository guidance, and only the project evidence needed to understand the language. Treat a stable project-specific meaning as resolved when that context makes it clear. Challenge uses that conflict with an established term. +## Method -### 2. Update inline +1. **Ground the language.** Compare every affected term with the glossary and relevant evidence, including meanings already resolved in the incoming context. Use canonical terms in the dialogue. +2. **Sharpen the model.** Challenge vague, overloaded, or conflicting terms. Propose precise canonical names and test conceptual boundaries with concrete scenarios. Ask one resolving question at a time when intent remains unclear. During `$elicit`, put these questions into its active decision tree. Preserve unresolved entries. Report code or document discrepancies against confirmed intended meaning to the caller without reopening settled intent. +3. **Write immediately.** As soon as a meaning resolves, write it to `GLOSSARY.md` and read the affected entries back **before the next question or dependent work**. Do this for supplied meanings before questioning begins and after each answer or discovery. Never queue definitions for a batch or wait for the final synthesis. Routine resolved updates need no separate approval. +4. **Reconcile affected entries.** Create the root file lazily. Preserve local formatting and unrelated terms, update existing entries, and remove duplicates. Define each canonical term in one or two project-native sentences. Qualify legitimately different meanings within the root glossary. Retain aliases, discouraged synonyms, or deprecations only while they help interpret project evidence. Keep general programming concepts, specifications, and implementation rationale in their own authorities. -Update `GLOSSARY.md` as each meaning resolves, before the surrounding work continues. Do not request approval or announce the skill. Add no separate verification or handoff for a routine glossary update; follow the surrounding task's normal checks and reporting. +Use [the glossary template](assets/glossary-template.md) when creating the first glossary. Group related concepts when useful. -When ambiguity, conflict, rename, or deprecation could materially change the meaning, ask one direct question that distinguishes the alternatives. Preserve the existing entry until the answer resolves the meaning. +For example, if Reservation is resolved while its expiry policy remains open, write Reservation now and continue questioning about expiry. Keep the expiry rule with its specification. -Create the root file lazily from the [glossary template](assets/glossary-template.md). Preserve unrelated terms and local format. Edit only affected entries, prefer updating an entry to adding a duplicate, and reconcile resolved changes across affected entries. Retain an alias or deprecation only while it helps interpret current project evidence. +## Finish -Keep `GLOSSARY.md` a glossary, not a specification or implementation record. Give each canonical term one short project-native paragraph; group terms by domain only when useful. +Keep routine resolved updates silent in progress messages and the final handoff. Report only material discrepancies, unresolved meanings, or write failures through the caller. Leave code and other document repairs with the caller. + +**Done only when** every resolved affected meaning is written and checked, affected entries are consistent, and every unresolved meaning is explicitly reported unchanged. A failed write leaves maintenance incomplete. Continue maintaining the glossary while the surrounding conversation proceeds. diff --git a/skills/maintain-ubiquitous-language/agents/openai.yaml b/skills/maintain-ubiquitous-language/agents/openai.yaml index 3a8cfa7..adff569 100644 --- a/skills/maintain-ubiquitous-language/agents/openai.yaml +++ b/skills/maintain-ubiquitous-language/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Maintain Ubiquitous Language' - short_description: 'Maintain shared project terminology' -policy: - allow_implicit_invocation: false + short_description: 'Sharpen and immediately capture project meanings' diff --git a/skills/maintain-ubiquitous-language/assets/glossary-template.md b/skills/maintain-ubiquitous-language/assets/glossary-template.md index 5d11007..73b7ba4 100644 --- a/skills/maintain-ubiquitous-language/assets/glossary-template.md +++ b/skills/maintain-ubiquitous-language/assets/glossary-template.md @@ -1,4 +1,4 @@ -# {Project Name} Glossary +# {Project name} glossary ## Language diff --git a/skills/measure-code-complexity/SKILL.md b/skills/measure-code-complexity/SKILL.md index add0e04..d8ce3ba 100644 --- a/skills/measure-code-complexity/SKILL.md +++ b/skills/measure-code-complexity/SKILL.md @@ -1,54 +1,43 @@ --- name: measure-code-complexity -description: Measures changed-code complexity with pinned cross-language metrics and advisory review triggers. Use when implementing, reviewing, or directly assessing code complexity. -metadata: - type: utility -disable-model-invocation: false +description: Measure current code complexity when a caller needs scores and interpretation to guide refactoring. --- -# Measure Code Complexity +# Measure code complexity -Measures reproducible complexity signals and routes triggered changed code through contextual engineering judgement. +Measure current code and explain signals that warrant attention. **The caller owns changes and comparisons.** -## Prerequisites +## Inputs -Fix the Git repository, candidate, comparison base, caller authority, and any explicit repository thresholds. Require Python 3.8 or newer. Report the exact unavailable or incomplete evidence when any prerequisite is absent; never treat a failed or unsupported measurement as clear. +Measure the production files selected by the request. Default to every function in changed production files, including eligible untracked files. A supplied Git base selects files only, defaulting to `HEAD`. Requires Git and Python 3.9 or newer. Supports macOS and Linux on ARM64 or x64, and Windows x64 with the Visual C++ runtime. -## Process +## Method -### 1. Measure the fixed change +1. **Run the CLI.** Read [the CLI contract](references/cli.md) when selecting files, inspecting report fields or resolving a limitation. -Run the bundled [measurement script](scripts/measure.py) without installing dependencies or accessing the network: + ```sh + python3 /path/to/measure-code-complexity/scripts/measure.py --repo /repo + ``` -```sh -python3 /path/to/measure-code-complexity/scripts/measure.py \ - --repo /path/to/repository \ - --base -``` + Read the compact summary and saved report. Inspect status and limitations before interpreting scores. -Pass the corresponding threshold option when an explicit repository policy overrides a bundled default. Use `--whole-repository` only for an explicit repository-wide request and `--all` only when compact evidence cannot resolve a concrete question. +2. **Collect available native CRAP.** Inspect installed packages, test commands and reporting support. If usable, read [native collection](references/native-crap.md), reuse a proven current report or run the existing command with its supported reporting option. Keep native scores and provenance as supplementary evidence. Omit unavailable CRAP. Report actual attempted failures. +3. **Interpret the scores.** Load each reference whose condition is met and follow its guidance. Use individual function or method scores for the conditions below. -### 2. Investigate triggered signals + | Signal | Load when | Reference | + | -------------------- | ---------------------------- | ------------------------------------------------------------ | + | CC | ≥10 | [Cyclomatic complexity](references/cyclomatic-complexity.md) | + | Cognitive Complexity | >15 | [Cognitive complexity](references/cognitive-complexity.md) | + | Function NLOC | >60 | [Function size](references/function-size.md) | + | Maximum nesting | ≥4 | [Nesting](references/nesting.md) | + | Parameters | ≥6 | [Parameters](references/parameters.md) | + | Duplication | A span of ≥70 tokens repeats | [Duplication](references/duplication.md) | + | Native CRAP | ≥30 | [CRAP](references/crap.md) | -Read the compact JSON. Its summary accounts for every measured changed function; detailed records default to triggered entities and the raw artifact retains the complete normalized result. + Read relevant records from the saved report instead of dumping it into context. Scores prompt consideration, not a quality verdict or compulsory refactoring. -For each triggered metric, load only its named reference: [Cyclomatic Complexity](references/CYCLOMATIC-COMPLEXITY.md), [Function Size](references/FUNCTION-SIZE.md), [Nesting](references/NESTING.md), [Parameters](references/PARAMETERS.md), or [Duplication](references/DUPLICATION.md). Inspect the cited source, nearby contracts, tests, and clone counterparts. Do not load a metric reference that did not trigger. +## Finish -Disposition every trigger as one of: +Return the compact measurements, report path, interpretation of triggered metrics, available native CRAP with provenance, and material limitations. Leave refactoring, testing decisions, subsequent calls and comparisons to the caller. -- **Supported concern:** state the concrete maintainability consequence, evidence, and narrow improvement direction. -- **Justified shape:** state the concrete code- and test-based reason the shape is appropriate. -- **Unresolved:** state the missing authority or evidence and leave the trigger open. - -Measure and interpret only. Leave every source edit, test run, and decision to apply an improvement to the caller. - -### 3. Return the evidence - -Return the fixed scope, compact summary, triggered locations and values, baseline deltas when present, each disposition, incomplete evidence, and raw-artifact path. A high value triggers inspection; it does not establish a defect, require refactoring, or supply a code-quality verdict. - -## Rules - -- Keep the bundled metric definitions and bands intact unless explicit repository policy overrides a threshold. -- Preserve all metric components; do not combine them into Maintainability Index, CRAP, or another scalar grade. -- Reject score-only changes that merely move branching, add indirection, hide parameters, or replace one clone with a shallow abstraction. -- Stop after every trigger has a supported disposition or is explicitly unresolved. Do not modify source or tests, run implementation checks, create repository policy or durable reports, commit, publish, or change external state. +**Done only when** selected files are accounted for, available measurements are reported, triggered metrics are interpreted and incomplete evidence remains explicit. Missing native CRAP is a valid omission. An attempted measurement failure leaves that measurement unresolved. diff --git a/skills/measure-code-complexity/agents/openai.yaml b/skills/measure-code-complexity/agents/openai.yaml index 46dd2f9..48f4af0 100644 --- a/skills/measure-code-complexity/agents/openai.yaml +++ b/skills/measure-code-complexity/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Measure Code Complexity' - short_description: 'Measure changed-code complexity and review triggers' -policy: - allow_implicit_invocation: true + short_description: 'Measure current code and interpret complexity signals' diff --git a/skills/measure-code-complexity/references/CYCLOMATIC-COMPLEXITY.md b/skills/measure-code-complexity/references/CYCLOMATIC-COMPLEXITY.md deleted file mode 100644 index fba7a8a..0000000 --- a/skills/measure-code-complexity/references/CYCLOMATIC-COMPLEXITY.md +++ /dev/null @@ -1,9 +0,0 @@ -# Cyclomatic Complexity - -Cyclomatic complexity counts recognized decision points within each function as a control-flow-path proxy. Use the bundled bands as attention routing: `1-6` low, `7-9` moderate, `10-20` high, and `21+` very high. Values differ across measurement engines and languages; this does not measure all executable paths, nesting, domain difficulty, runtime behaviour, or correctness. - -Inspect whether the branches represent one cohesive decision, repeated cases, invalid intermediate states, flag-driven behaviour, or several policies sharing a function. Trace the distinct outcomes and their tests. - -Prefer guard clauses for invalid states, data or lookup tables for declarative cases, and extraction behind a named boundary when a decision has an independent contract. Use polymorphism or strategy objects only when the variants are real concepts with separate change patterns. Do not improve the number by scattering the same decisions across shallow helpers. - -Retain high complexity when an explicit algorithm, parser, state transition, protocol, or irreducible domain rule is clearer locally and its material paths are tested. Record that mechanism and evidence. diff --git a/skills/measure-code-complexity/references/DUPLICATION.md b/skills/measure-code-complexity/references/DUPLICATION.md deleted file mode 100644 index 511f65a..0000000 --- a/skills/measure-code-complexity/references/DUPLICATION.md +++ /dev/null @@ -1,9 +0,0 @@ -# Duplication - -Clone detection normalizes token sequences and reports locations meeting the bundled `70`-token floor. Review new or expanded clone groups that intersect changed code. A clone is syntactic similarity, not proof that occurrences share one concept or should evolve together. - -Compare every occurrence. Inspect whether the same rule, defect fix, invariant, or sequence would need parallel change; also check whether similarities are coincidental, generated, declarative, protocol-defined, or intentionally independent test examples. - -Prefer one owner with a deep interface when the occurrences share knowledge and change together. Use data tables or parameterized tests when only values differ. Do not create a shallow helper that leaks sequencing, accepts mode flags, couples independent features, or obscures a readable example. - -Retain a clone when independent evolution, protocol fidelity, test clarity, or a small stable repetition outweighs shared ownership. Record that reason and the evidence that future changes need not stay synchronized. diff --git a/skills/measure-code-complexity/references/FUNCTION-SIZE.md b/skills/measure-code-complexity/references/FUNCTION-SIZE.md deleted file mode 100644 index bcbefda..0000000 --- a/skills/measure-code-complexity/references/FUNCTION-SIZE.md +++ /dev/null @@ -1,9 +0,0 @@ -# Function Size - -NLOC counts non-comment source lines within a function; token count is supporting scale evidence. Review NLOC above `100`. Size measures change surface, not value, productivity, correctness, or understandability, and formatting or language syntax can change it. - -Inspect whether the function mixes validation, policy, transformation, persistence, external effects, or several temporal phases. Look for a coherent block with its own inputs, result, invariant, and useful name rather than extracting by line count. - -Prefer a smaller deep helper, a table for repetitive data, or an owned module when that improves locality and hides a real decision. Keep related sequencing together when extraction would force callers to coordinate it or create pass-through methods. - -Retain long linear functions when they are declarative mappings, protocol mirrors, migrations, generated structures, or one readable algorithm whose split would obscure the flow. Verify the retained shape through focused tests and the applicable repository checks. diff --git a/skills/measure-code-complexity/references/NESTING.md b/skills/measure-code-complexity/references/NESTING.md deleted file mode 100644 index b9d29ec..0000000 --- a/skills/measure-code-complexity/references/NESTING.md +++ /dev/null @@ -1,9 +0,0 @@ -# Nested Control Structures - -The nested-structures metric reports the maximum number of nested control structures in a function. Review values above `3`. It is a syntactic proxy for context carried through nested branches; it is not Cognitive Complexity and may vary with language support. - -Inspect which conditions protect invalid states, which levels represent independent policy, and whether loop, exception, and conditional nesting obscure the active invariant. Trace the deepest path and its tests. - -Prefer guard clauses, `continue` or early completion for invalid cases, named predicates, and extraction of a cohesive nested policy. Flatten only when the resulting order and effects remain explicit. Avoid boolean flags, callback chains, or hidden mutable state that reduce indentation while increasing coordination. - -Retain nesting when tree traversal, parsing, structured resource handling, or transactional cleanup is clearest in its lexical hierarchy. Record why flattening would weaken correctness or locality and identify the tests protecting the deepest path. diff --git a/skills/measure-code-complexity/references/PARAMETERS.md b/skills/measure-code-complexity/references/PARAMETERS.md deleted file mode 100644 index 0936b80..0000000 --- a/skills/measure-code-complexity/references/PARAMETERS.md +++ /dev/null @@ -1,9 +0,0 @@ -# Parameter Count - -The measurement reports a function parameter count. Verify it against the signature before dispositioning it because partial language parsers can miscount parameters. Review counts of `5` or more. The count can expose a wide interface or recurring data group, but it does not measure parameter meaning, type safety, defaults, or the depth of the function's abstraction. - -Inspect whether parameters travel together, represent one concept, encode flags or modes, or change for unrelated reasons. Check call sites before changing the interface. - -Prefer an existing domain value, an explicit request or options type with a coherent invariant, or separate operations when callers currently select unrelated behaviour. Do not hide unrelated values in a generic bag or move required context into globals, ambient state, or service locators. - -Retain a wider signature for mathematical functions, stable interoperation boundaries, framework callbacks, or flat data construction when grouping would add ceremony without ownership. Record the caller evidence and keep meaningful parameter names and types. diff --git a/skills/measure-code-complexity/references/cli.md b/skills/measure-code-complexity/references/cli.md new file mode 100644 index 0000000..e3ddb5c --- /dev/null +++ b/skills/measure-code-complexity/references/cli.md @@ -0,0 +1,35 @@ +# Measurement CLI + +Use `scripts/measure.py --help` for arguments. Requires Git and Python 3.9 or newer. Supported hosts are macOS and Linux on ARM64 or x64, and Windows x64 with the Visual C++ runtime. No complexity-tool installation or download is needed. The helper writes its executable cache and full JSON outside the repository, and leaves project files unchanged. + +## Select current files + +By default, measure changed production files relative to `HEAD`, including staged, unstaged and eligible untracked files. Every recognised function in those files is measured. `--base ` changes file selection only. + +Pass explicit files relative to the repository to stabilise scope across refactoring runs or include related files. + +```sh +python3 /path/to/measure.py --repo /repo src/quote.ts src/rules.ts +``` + +Conventional tests, fixtures, dependencies, generated output and non-source formats are excluded and listed in the report. Explicit paths must name files inside the repository. Keep selected files fixed during measurement. An empty selection supplies no function evidence. + +## Read the report + +Stdout contains status, summary, scope, producing versions, limitation count and the report path. Full JSON contains `files`, functions and nested `children`. File totals include module-level code. Summary distributions describe functions, with separate populations for supporting measurements under `summary.lizard`. Missing measurements are absent, never zero. + +Function records contain `cyclomatic` and `cognitive`. Supporting fields under `lizard` are `nloc`, `parameters`, `max_nesting` and `end_line`. Ambiguous supporting records retain their own locations under `lizard_unmatched`. `duplicates` supplies clone groups and locations. `summary.attention` counts records meeting the interpretation conditions in the skill. + +Read only needed records. For example, select one file without printing the entire report. + +```sh +jq '.files[] | select(.path == "src/quote.ts")' /tmp/code-complexity-report.json +``` + +`scope.content_id` identifies selected paths and contents. It does not identify tests, configuration or a native reporting run. Keep producing versions and scope alongside comparisons. + +## Limits and failure + +Exit 0 means a report was produced, including `partial` results. Read the full `limitations` list whenever its count is non-zero. Unsupported source, parse errors and incomplete joins remain explicit. Exit 2 means invalid input or a failed prerequisite or command. Argument errors go to stderr. Resolve the reported cause before rerunning. + +Recognition can affect function boundaries and parameter counts. A file with no recognised functions may contain executable module code. Command execution is bounded to 60 seconds. Selected-source changes during collection invalidate the measurement. Native CRAP reporting is separate. diff --git a/skills/measure-code-complexity/references/cognitive-complexity.md b/skills/measure-code-complexity/references/cognitive-complexity.md new file mode 100644 index 0000000..a12d737 --- /dev/null +++ b/skills/measure-code-complexity/references/cognitive-complexity.md @@ -0,0 +1,34 @@ +# Cognitive complexity + +Cognitive Complexity weights breaks in linear flow and nesting to approximate understanding burden. A straight-line function starts at 0. A nested decision costs more than the same decision at the outer level. It complements CC, which describes independent paths. + +| Score | Advisory band | Meaning | +| ----- | ------------- | --------------------------------------------------- | +| 0–7 | Low | Little structural flow to hold in mind | +| 8–15 | Moderate | Several flow changes need attention | +| 16–25 | High | Inspect nested decisions and mixed levels of detail | +| >25 | Very high | Substantial structural reasoning burden | + +These bands are advisory heuristics. Language conventions and domain difficulty affect reading burden, so no score establishes a universal readability boundary. + +**Replace Nested Conditional with Guard Clauses** can flatten rejection paths. This illustrative transformation preserves outcome and failure precedence. CC stays 3 while Cognitive Complexity falls from 3 to 2. + +```ts +// Before +function offer(active: boolean, held: boolean) { + if (active) { + if (held) return 'held'; + return 'offer'; + } + return 'inactive'; +} + +// After +function offer(active: boolean, held: boolean) { + if (!active) return 'inactive'; + if (held) return 'held'; + return 'offer'; +} +``` + +Also consider naming a compound condition or separating unrelated decisions. Preserve evaluation order and cleanup. A low score can still hide state, indirection or a difficult domain rule. Extract meaningful knowledge, not arbitrary chunks solely to reduce a score. diff --git a/skills/measure-code-complexity/references/crap.md b/skills/measure-code-complexity/references/crap.md new file mode 100644 index 0000000..8764797 --- /dev/null +++ b/skills/measure-code-complexity/references/crap.md @@ -0,0 +1,21 @@ +# CRAP + +Change Risk Anti-Patterns combines a method's cyclomatic complexity and automated test coverage to describe exposure when changing code. Its conventional formula uses coverage fraction `c` from 0 to 1. + +```text +CRAP = CC² × (1 − c)³ + CC +``` + +| Score | Advisory band | Meaning | +| ------ | --------------- | -------------------------------------------------------- | +| <30 | Below attention | Lower combined complexity and uncovered-code exposure | +| 30–<60 | Attention | Inspect complexity and protection of supported behaviour | +| ≥60 | High | Prioritise understanding the combined change exposure | + +Apply these advisory bands to method scores. Aggregate sums and file-level averages change with population size and can hide individual high scores. + +At CC 10, the conventional formula gives 110 with no coverage, 22.5 with half coverage and 10 with full coverage. Full coverage leaves complexity visible. It does not prove that assertions check the right behaviour. + +Producers can use different coverage definitions or formula adjustments. Interpret the reported score using its recorded provenance. Preserve the native value rather than calculating a replacement from separate measurements. + +Consider whether the caller can simplify accidental complexity or improve behavioural protection within its authorised task. Testing decisions remain with the caller. Do not add tests just to lower CRAP. A score is an inspection signal, not a defect, assurance of correctness or permission to finish. diff --git a/skills/measure-code-complexity/references/cyclomatic-complexity.md b/skills/measure-code-complexity/references/cyclomatic-complexity.md new file mode 100644 index 0000000..8b24c02 --- /dev/null +++ b/skills/measure-code-complexity/references/cyclomatic-complexity.md @@ -0,0 +1,16 @@ +# Cyclomatic complexity + +CC counts independent control-flow paths. A function begins at 1. Each recognised decision adds paths. This describes path reasoning and testing burden, not all possible executions or nesting. + +| Score | Band | Meaning | +| ----- | --------- | -------------------------------------------------------------- | +| 1–6 | Low | Few independent paths | +| 7–9 | Moderate | Several cases to reason about | +| 10–20 | High | Inspect branch interactions and mixed responsibilities | +| >20 | Very high | Prioritise understanding the path structure before changing it | + +These bands are advisory. Language and scoring conventions can affect decision counts. A CC value is not a required number of branch-coverage tests or a correctness grade. + +For example, nine independent `if` decisions yield CC 10. If they repeatedly reconstruct one supported mapping, consider centralising that mapping. If they represent distinct necessary domain cases, keeping them together may be clearer. + +Consider **Decompose Conditional**, **Substitute Algorithm** or a coherent extraction when it reduces decisions the reader must reconstruct. Preserve failure precedence, defaults and effect order. Moving the same branches into tiny wrappers or callbacks can lower one function's score while increasing indirection. The caller decides whether source evidence supports a change. diff --git a/skills/measure-code-complexity/references/duplication.md b/skills/measure-code-complexity/references/duplication.md new file mode 100644 index 0000000..63f91b8 --- /dev/null +++ b/skills/measure-code-complexity/references/duplication.md @@ -0,0 +1,16 @@ +# Duplication + +Duplication measures repeated token spans within selected files at a minimum of 70 tokens. The report gives each observed group and source location. The summary rate is a fraction from 0 to 1 over the selected token population. It is not a percentage of duplicated lines or a repository-wide rate. + +| Observation | Interpretation | +| ---------------------------------------- | --------------------------------------------------------- | +| No detected groups | No repeats at this detector's span size within this scope | +| One or more groups | Inspect whether the locations repeat one domain decision | +| Shared policy confirmed across locations | Changes must find and update each copy | +| Similar syntax with independent policies | Consolidation may create false coupling | + +There is no universal good or bad rate. Detection depends on language, normalisation, exclusions and span size. Zero detected groups does not prove DRY. + +For example, two copies of the same eligibility rule can cause **Shotgun Surgery**. Consider moving the decision to its domain owner and migrating callers together. Similar validation loops for unrelated protocols can be **incidental duplication**, where shared abstraction would couple independent change reasons. + +Use **DRY** for knowledge, not visual similarity. The caller inspects authority, callers and compatibility before choosing consolidation. A smaller clone rate alone does not justify an abstraction. diff --git a/skills/measure-code-complexity/references/function-size.md b/skills/measure-code-complexity/references/function-size.md new file mode 100644 index 0000000..3cd95c4 --- /dev/null +++ b/skills/measure-code-complexity/references/function-size.md @@ -0,0 +1,16 @@ +# Function size + +**NLOC** counts non-comment source lines in a function. Formatting, language syntax and nested-function attribution can affect the count. Compare measurements with the same definition and scope. + +| NLOC | Advisory band | Meaning | +| ------ | ------------- | --------------------------------------------------------------- | +| ≤30 | Compact | Little source to scan | +| 31–60 | Substantial | More material to retain while reading | +| 61–100 | Large | Inspect whether distinct responsibilities obscure the operation | +| >100 | Very large | Substantial source-reading burden | + +These are local review heuristics, not language-independent quality limits. A cohesive algorithm can earn its size. + +For example, a 75-line operation that decodes an invoice and separately implements carrier policy may have two change reasons. Consider separating the carrier decision. A 75-line invoice grammar may be clearer as one deep operation with private phases. + +Consider deletion of dead branches, consolidation of repeated work or **Extract Function** for a complete, nameable responsibility. Preserve state, effects, ordering and the supported interface. Minifying code, deleting useful explanations or creating a chain of shallow helpers improves a count without reducing reader burden. diff --git a/skills/measure-code-complexity/references/native-crap.md b/skills/measure-code-complexity/references/native-crap.md new file mode 100644 index 0000000..33c6447 --- /dev/null +++ b/skills/measure-code-complexity/references/native-crap.md @@ -0,0 +1,9 @@ +# Collect native CRAP + +Inspect installed packages, test configuration, repository commands and supported reporting options. Verify uncertain flags against installed help or source. A test framework or coverage reporter alone does not establish CRAP support. Required instrumentation must already work. + +Reuse a report only when its source, tests, configuration, command, tool version and scope are established as current. Otherwise run the project's existing test command with its supported CRAP report option. Preserve suite selection, exclusions, fixtures, runtime and thresholds. Write to a fresh temporary destination outside the repository. Reuse an ordinary verification run where possible. + +Inspect the actual report. A successful command or requested filename without usable scores establishes no measurement. Check that source, tests and configuration stayed unchanged during collection. Record command, exit result, producing versions, source and test scope, and report path. The static CLI's content identity covers only selected source. + +Retain native method identities and scores exactly as produced. Native tools own their complexity, coverage definition and formula. Keep them separate from static measurements. An unmatched method supplies no score. Install no packages, add no configuration or tests, and calculate no substitute CRAP from separate coverage. Without a usable facility, omit CRAP without setup advice or a testing-gap report. Report an attempted failure or stale report as an evidence limitation. diff --git a/skills/measure-code-complexity/references/nesting.md b/skills/measure-code-complexity/references/nesting.md new file mode 100644 index 0000000..2beafb6 --- /dev/null +++ b/skills/measure-code-complexity/references/nesting.md @@ -0,0 +1,15 @@ +# Maximum nesting + +Maximum nesting counts simultaneously nested control structures. This is syntactic depth, not a Cognitive Complexity score. Treatment of comprehensions, expressions and nested functions can differ across languages. + +| Depth | Advisory band | Meaning | +| ----- | ------------- | -------------------------------------------------------- | +| 0–1 | Shallow | Little enclosing control state | +| 2–3 | Nested | Several active conditions or loops | +| ≥4 | Deep | Inspect the successful path and state held across levels | + +These are local interpretation heuristics. A necessary traversal may justify deeper nesting. + +For example, `loop → if → loop → if` has depth 4. Consider rejecting ineligible outer cases before the inner traversal, or extracting a complete inner operation when it owns a coherent decision. **Replace Nested Conditional with Guard Clauses** can reveal the main path. + +Preserve iteration order, failure precedence, resource cleanup and effects. An early return inside a resource lifecycle can change behaviour. Replacing loops with nested callbacks can hide the same depth behind additional indirection. diff --git a/skills/measure-code-complexity/references/parameters.md b/skills/measure-code-complexity/references/parameters.md new file mode 100644 index 0000000..a23727b --- /dev/null +++ b/skills/measure-code-complexity/references/parameters.md @@ -0,0 +1,15 @@ +# Parameter count + +Parameter count describes the declared inputs to a function. Syntax can affect recognition. Retain the measured value and expose observed discrepancies rather than silently replacing it. + +| Parameters | Advisory band | Meaning | +| ---------- | ------------- | ---------------------------------------------- | +| 0–3 | Small | Few inputs for callers to distinguish | +| 4–5 | Substantial | More input meanings and interactions | +| ≥6 | Large | Inspect the interface and repeated data clumps | + +These are local review heuristics. Independent inputs can form the simplest honest interface. + +Consider **Remove Parameter** when unused, **Replace Parameter with Query** when the owner already holds the value, or **Introduce Parameter Object** for a real domain concept. For example, an account and statement period travelling together may earn a `StatementRequest`. Six unrelated inputs do not become simpler when hidden in an unnamed options bag. + +Keep supported external signatures and runtime defaults. The caller establishes whether grouping reduces knowledge or merely hides the parameter list. diff --git a/skills/measure-code-complexity/scripts/bundled_cccc.py b/skills/measure-code-complexity/scripts/bundled_cccc.py new file mode 100644 index 0000000..0343f5f --- /dev/null +++ b/skills/measure-code-complexity/scripts/bundled_cccc.py @@ -0,0 +1,68 @@ +"""Select and verify the bundled cccc release. Cache only the executable outside the repository.""" + +import getpass +import hashlib +import json +import os +from pathlib import Path +import platform +import tarfile +import tempfile +import zipfile + +BUNDLE = Path(__file__).resolve().parent / "vendor" / "cccc" +TARGETS = { + ("Darwin", "arm64"): "aarch64-apple-darwin", + ("Darwin", "x86_64"): "x86_64-apple-darwin", + ("Linux", "arm64"): "aarch64-unknown-linux-musl", + ("Linux", "x86_64"): "x86_64-unknown-linux-musl", + ("Windows", "x86_64"): "x86_64-pc-windows-msvc", +} + + +def target(system=None, machine=None): + system = system or platform.system() + machine = (machine or platform.machine()).lower() + machine = {"aarch64": "arm64", "amd64": "x86_64"}.get(machine, machine) + if (system, machine) not in TARGETS: + raise ValueError(f"No bundled binary for {system} {machine}. Supported: macOS/Linux ARM64 or x64, Windows x64.") + return TARGETS[system, machine] + + +def executable(): + spec = json.loads((BUNDLE / "manifest.json").read_text())["targets"][target()] + archive = BUNDLE / spec["archive"] + if hashlib.sha256(archive.read_bytes()).hexdigest() != spec["archive_sha256"]: + raise ValueError(f"Bundled archive checksum mismatch: {archive.name}") + user = str(os.getuid()) if hasattr(os, "getuid") else hashlib.sha256(getpass.getuser().encode()).hexdigest()[:16] + cache = Path(tempfile.gettempdir()) / f"propulsion-cccc-{user}" + if cache.is_symlink(): + raise ValueError(f"Expected a regular cache directory: {cache}") + cache.mkdir(mode=0o700, exist_ok=True) + if hasattr(os, "getuid") and cache.stat().st_uid != os.getuid(): + raise ValueError(f"Cache directory belongs to another user: {cache}") + binary = cache / (spec["binary_sha256"] + Path(spec["member"]).suffix) + if binary.is_symlink(): + raise ValueError(f"Expected a regular cached executable: {binary}") + if binary.exists(): + if hashlib.sha256(binary.read_bytes()).hexdigest() != spec["binary_sha256"]: + raise ValueError(f"Cached executable checksum mismatch. Remove {binary} and rerun.") + return str(binary) + if archive.suffix == ".zip": + with zipfile.ZipFile(archive) as package: + data = package.read(spec["member"]) + else: + with tarfile.open(archive) as package: + data = package.extractfile(spec["member"]).read() + if hashlib.sha256(data).hexdigest() != spec["binary_sha256"]: + raise ValueError(f"Bundled executable checksum mismatch: {archive.name}") + descriptor, temporary = tempfile.mkstemp(dir=cache) + try: + with os.fdopen(descriptor, "wb") as stream: + stream.write(data) + os.chmod(temporary, 0o755) + os.replace(temporary, binary) + finally: + if os.path.exists(temporary): + os.unlink(temporary) + return str(binary) diff --git a/skills/measure-code-complexity/scripts/measure.py b/skills/measure-code-complexity/scripts/measure.py index a537d3c..262984e 100644 --- a/skills/measure-code-complexity/scripts/measure.py +++ b/skills/measure-code-complexity/scripts/measure.py @@ -1,738 +1,312 @@ #!/usr/bin/env python3 -"""Measure changed-code complexity with a pinned, vendored Lizard runtime.""" +"""Measure current production files with cccc and Lizard. Save full JSON, print a compact summary.""" from __future__ import annotations import argparse +from collections import defaultdict import hashlib -import itertools import json +import math import os from pathlib import Path import re import subprocess import sys import tempfile -from typing import Any, Iterable +sys.dont_write_bytecode = True +from python_nesting import function_depths +from bundled_cccc import executable as bundled_cccc -SCHEMA_VERSION = 1 SCRIPT_ROOT = Path(__file__).resolve().parent -VENDOR_ROOT = SCRIPT_ROOT / "vendor" -WHEELS = ( - ( - "pygments-2.19.2-py3-none-any.whl", - "86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", - ), - ( - "lizard-1.24.0-py2.py3-none-any.whl", - "a688bc607a891ff4a7836826f25742dc9c1bf648da3075dbd495e199e8848602", - ), -) - -DEFAULTS = { - "cyclomaticReview": 10, - "nlocReview": 100, - "nestedStructuresReview": 3, - "parameterCountReview": 5, - "duplicateTokens": 70, +WHEELS = { + "pygments-2.19.2-py3-none-any.whl": "86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", + "lizard-1.24.0-py2.py3-none-any.whl": "a688bc607a891ff4a7836826f25742dc9c1bf648da3075dbd495e199e8848602", } - -REFERENCES = { - "cyclomaticComplexity": "references/CYCLOMATIC-COMPLEXITY.md", - "nloc": "references/FUNCTION-SIZE.md", - "nestedStructures": "references/NESTING.md", - "parameterCount": "references/PARAMETERS.md", - "duplication": "references/DUPLICATION.md", +EXCLUDED = { + ".git", ".hg", ".svn", "node_modules", "vendor", "vendors", "deps", + "build", "dist", "target", "coverage", "generated", "fixtures", + "snapshots", "__fixtures__", "__snapshots__", "__pycache__", + "test", "tests", "spec", "specs", "__tests__", } - -EXCLUDED_SEGMENTS = { - ".git", - ".hg", - ".svn", - "build", - "coverage", - "deps", - "dist", - "fixtures", - "generated", - "node_modules", - "snapshots", - "vendor", - "vendors", - "__fixtures__", - "__snapshots__", +NON_SOURCE = { + ".css", ".csv", ".gif", ".html", ".ico", ".info", ".jpeg", ".jpg", + ".json", ".jsonc", ".lcov", ".lock", ".map", ".md", ".mdx", ".pdf", + ".png", ".pyc", ".snap", ".svg", ".toml", ".tsv", ".txt", ".webp", + ".whl", ".xml", ".yaml", ".yml", } - -TEST_SEGMENTS = {"spec", "specs", "test", "tests", "__tests__"} -NON_SOURCE_SUFFIXES = { - ".css", - ".csv", - ".gif", - ".html", - ".jpeg", - ".jpg", - ".json", - ".lock", - ".md", - ".pdf", - ".png", - ".svg", - ".toml", - ".txt", - ".xml", - ".yaml", - ".yml", +CLONE_TOKENS = 70 +# Attention routes interpretation. It never controls success or changes scores. +ATTENTION = { + "cyclomatic": (10, "cyclomatic-complexity.md"), + "cognitive": (16, "cognitive-complexity.md"), + "nloc": (61, "function-size.md"), + "max_nesting": (4, "nesting.md"), + "parameters": (6, "parameters.md"), } class MeasurementError(RuntimeError): - """A deterministic measurement prerequisite or execution failed.""" - - -def sha256(path: Path) -> str: - digest = hashlib.sha256() - with path.open("rb") as stream: - for block in iter(lambda: stream.read(1024 * 1024), b""): - digest.update(block) - return digest.hexdigest() + pass -def load_analyzer() -> tuple[Any, Any, Any, str]: - if sys.version_info < (3, 8): - raise MeasurementError("Python 3.8 or newer is required.") - - for filename, expected in WHEELS: - wheel = VENDOR_ROOT / filename - if not wheel.is_file(): - raise MeasurementError(f"Missing vendored analyzer wheel: {filename}") - actual = sha256(wheel) - if actual != expected: - raise MeasurementError( - f"Checksum mismatch for {filename}: expected {expected}, got {actual}" - ) - sys.path.insert(0, str(wheel)) - - try: - import lizard # type: ignore - from lizard_ext import lizardduplicate, lizardns, version # type: ignore - except (ImportError, SystemExit) as error: - raise MeasurementError(f"Unable to load vendored Lizard: {error}") from error - - return lizard, lizardns, lizardduplicate, str(version) - - -def git(repo: Path, *arguments: str, check: bool = True) -> bytes: - command = ["git", "-C", str(repo), *arguments] - result = subprocess.run(command, capture_output=True, check=False) - if check and result.returncode != 0: - message = result.stderr.decode("utf-8", "replace").strip() - raise MeasurementError( - f"Command failed ({result.returncode}): {' '.join(command)}: {message}" - ) +def run(command, cwd=None): + result = subprocess.run(command, cwd=cwd, capture_output=True, text=True, timeout=60) + if result.returncode: + raise MeasurementError(f"Command failed ({result.returncode}): {' '.join(command)}: {result.stderr.strip()}") return result.stdout -def nul_fields(data: bytes) -> list[str]: - return [field.decode("utf-8", "surrogateescape") for field in data.split(b"\0") if field] +def git(repo, *arguments): + return run(["git", "-C", str(repo), *arguments]) -def normalize_path(value: str) -> str: - return Path(value).as_posix().removeprefix("./") +def fields(text): + return [part for part in text.split("\0") if part] -def excluded(path: str) -> bool: - normalized = normalize_path(path) - parts = set(Path(normalized).parts) - name = Path(normalized).name.lower() +def excluded(path): + name = path.name.lower() return ( - bool(parts & EXCLUDED_SEGMENTS) - or bool(parts & TEST_SEGMENTS) - or name.endswith((".min.js", ".min.css", ".generated.ts", ".generated.js")) - or ".fixture." in name - or ".snap." in name - or name.endswith((".spec.ts", ".spec.tsx", ".test.ts", ".test.tsx")) + bool(set(path.parts) & EXCLUDED) + or path.suffix.lower() in NON_SOURCE + or name.endswith((".min.js", ".generated.ts", ".generated.js")) + or ".fixture." in name or ".snap." in name + or re.search(r"\.(?:spec|test)\.(?:[cm]?[jt]sx?)$", name) + or (path.suffix.lower() in {".py", ".pyw"} and (name.startswith("test_") or name.endswith("_test.py") or name == "conftest.py")) + or name.endswith(("_test.go", "_spec.rb")) + or re.search(r"Tests?\.(?:java|cs)$", path.name) ) -def parse_name_status(data: bytes) -> dict[str, str | None]: - fields = nul_fields(data) - changed: dict[str, str | None] = {} - index = 0 - while index < len(fields): - status = fields[index] - index += 1 - if status.startswith(("R", "C")): - if index + 1 >= len(fields): - raise MeasurementError("Malformed git rename/copy status output.") - old_path = normalize_path(fields[index]) - new_path = normalize_path(fields[index + 1]) - changed[new_path] = old_path - index += 2 +def select_files(repo, paths, base): + if paths: + candidates = [] + for value in paths: + path = Path(os.path.abspath(repo / value)) + if not path.is_file() or not path.is_relative_to(repo) or not path.resolve().is_relative_to(repo): + raise MeasurementError(f"Expected a file inside --repo: {value}") + candidates.append(str(path.relative_to(repo))) + selection = {"mode": "explicit"} + else: + revision = git(repo, "rev-parse", "--verify", "--end-of-options", f"{base}^{{commit}}").strip() + candidates = fields(git(repo, "diff", "--name-only", "-z", "--diff-filter=ACMR", revision, "--")) + candidates += fields(git(repo, "ls-files", "--others", "--exclude-standard", "-z")) + selection = {"mode": "changed-files", "selection_base": revision} + selected, ignored = [], [] + for name in sorted(set(candidates)): + path = repo / name + if excluded(Path(name)): + ignored.append(name) + elif not path.is_file() or not path.resolve().is_relative_to(repo): + raise MeasurementError(f"Selected source is missing or resolves outside --repo: {name}") else: - if index >= len(fields): - raise MeasurementError("Malformed git name-status output.") - path = normalize_path(fields[index]) - index += 1 - if not status.startswith("D"): - changed[path] = path - return changed - - -def all_changed_paths(repo: Path, base: str) -> dict[str, str | None]: - changed = parse_name_status( - git(repo, "diff", "--name-status", "-z", "--find-renames", base, "--") - ) - for path in nul_fields(git(repo, "ls-files", "--others", "--exclude-standard", "-z")): - changed[normalize_path(path)] = None - return {path: old_path for path, old_path in changed.items() if (repo / path).is_file()} - - -def changed_paths(repo: Path, base: str) -> dict[str, str | None]: - return { - path: old_path - for path, old_path in all_changed_paths(repo, base).items() - if not excluded(path) - } - + selected.append(name) + return selected, {**selection, "files": selected, "excluded_files": ignored} -def line_ranges(repo: Path, base: str, path: str, is_untracked: bool) -> list[tuple[int, int]]: - if is_untracked: - line_count = sum(1 for _ in (repo / path).open("rb")) - return [(1, max(1, line_count))] - patch = git(repo, "diff", "--unified=0", "--no-color", base, "--", path).decode( - "utf-8", "replace" - ) - ranges: list[tuple[int, int]] = [] - for match in re.finditer(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", patch, re.MULTILINE): - start = int(match.group(1)) - count = int(match.group(2) or "1") - if count: - ranges.append((start, start + count - 1)) - return ranges - - -def intersects(start: int, end: int, ranges: Iterable[tuple[int, int]]) -> bool: - return any(start <= range_end and end >= range_start for range_start, range_end in ranges) - - -def current_paths(repo: Path) -> list[str]: - paths = nul_fields(git(repo, "ls-files", "-co", "--exclude-standard", "-z")) - return sorted( - { - normalize_path(path) - for path in paths - if (repo / path).is_file() and not excluded(path) - } - ) - - -def base_paths(repo: Path, base: str) -> list[str]: - return sorted( - path - for path in map( - normalize_path, - nul_fields(git(repo, "ls-tree", "-r", "--name-only", "-z", base)), - ) - if not excluded(path) - ) +def content_id(repo, paths): + digest = hashlib.sha256() + for name in paths: + digest.update(name.encode() + b"\0") + digest.update(hashlib.sha256((repo / name).read_bytes()).digest()) + return digest.hexdigest() -def source_paths(paths: Iterable[str], root: Path, lizard: Any) -> tuple[list[str], list[str]]: - supported: list[str] = [] - unsupported: list[str] = [] - for path in paths: - if lizard.get_reader_for(str(root / path)): - supported.append(path) - elif Path(path).suffix.lower() not in NON_SOURCE_SUFFIXES: - unsupported.append(path) - return supported, unsupported - - -def extract_base(repo: Path, base: str, paths: Iterable[str], target: Path) -> list[str]: - extracted: list[str] = [] - for path in paths: - result = subprocess.run( - ["git", "-C", str(repo), "show", f"{base}:{path}"], - capture_output=True, - check=False, - ) - if result.returncode != 0: - continue - destination = target / path - destination.parent.mkdir(parents=True, exist_ok=True) - destination.write_bytes(result.stdout) - extracted.append(path) - return extracted - - -def analyze( - root: Path, - paths: list[str], - lizard: Any, - lizardns: Any, - duplicate_module: Any, - duplicate_tokens: int, -) -> tuple[list[dict[str, Any]], list[list[dict[str, Any]]], float]: - nested_extension = lizardns.LizardExtension() - duplicate_extension = duplicate_module.LizardExtension() - extensions = lizard.get_extensions([nested_extension, duplicate_extension]) - absolute_paths = [str(root / path) for path in paths] - file_infos = list(lizard.analyze_files(absolute_paths, threads=1, exts=extensions)) - - functions: list[dict[str, Any]] = [] - for file_info in file_infos: - relative = normalize_path(os.path.relpath(file_info.filename, root)) - for function in file_info.function_list: - functions.append( - { - "file": relative, - "line": int(function.start_line), - "endLine": int(function.end_line), - "symbol": str(function.name), - "longName": str(function.long_name), - "metrics": { - "cyclomaticComplexity": int(function.cyclomatic_complexity), - "nloc": int(function.nloc), - "nestedStructures": int(function.max_nested_structures), - "parameterCount": int(function.parameter_count), - "tokenCount": int(function.token_count), - }, - } - ) - - duplicates: list[list[dict[str, Any]]] = [] - for group in duplicate_extension.get_duplicates(duplicate_tokens): - duplicates.append( - [ - { - "file": normalize_path(os.path.relpath(snippet.file_name, root)), - "line": int(snippet.start_line), - "endLine": int(snippet.end_line), - } - for snippet in group - ] - ) - return functions, duplicates, float(duplicate_extension.duplicate_rate() or 0.0) - - -def cyclomatic_band(value: int) -> str: - if value <= 6: - return "low" - if value <= 9: - return "moderate" - if value <= 20: - return "high" - return "veryHigh" - - -def baseline_match(function: dict[str, Any], base_functions: list[dict[str, Any]], old_path: str | None) -> dict[str, Any] | None: - if old_path is None: - return None - same_name = [ - item - for item in base_functions - if item["file"] == old_path and item["symbol"] == function["symbol"] +def load_lizard(): + for name, expected in WHEELS.items(): + path = SCRIPT_ROOT / "vendor" / name + if hashlib.sha256(path.read_bytes()).hexdigest() != expected: + raise MeasurementError(f"Vendored wheel checksum mismatch: {name}") + sys.path.insert(0, str(path)) + import lizard + from lizard_ext import lizardduplicate, lizardns, version + return lizard, lizardduplicate, lizardns, str(version) + + +def distribution(values): + values = sorted(values) + def percentile(percent): + return values[max(0, math.ceil(len(values) * percent / 100) - 1)] if values else 0 + return {"sum": sum(values), "max": max(values, default=0), "median": percentile(50), "p90": percentile(90), "p95": percentile(95)} + + +def functions(tree): + for function in tree: + yield function + yield from functions(function.get("children", [])) + + +def measure_cccc(repo, paths, executable): + version = run([executable, "--version"]).strip() + if not paths: + return {"files": [], "summary": { + "file_count": 0, "function_count": 0, "parse_error_count": 0, + "parse_error_file_count": 0, "cognitive": distribution([]), "cyclomatic": distribution([]), + }}, version + report = json.loads(run([executable, "--no-config", "--no-cache", "-j", "1", "--", *[str(repo / name) for name in paths]], cwd=repo)) + if not isinstance(report, dict) or not isinstance(report.get("files"), list) or not isinstance(report.get("summary"), dict): + raise MeasurementError("cccc returned an unsupported report shape. Expected files and summary.") + summary = report["summary"] + for key in ("file_count", "function_count", "parse_error_count", "parse_error_file_count"): + if type(summary.get(key)) is not int or summary[key] < 0: + raise MeasurementError(f"Invalid cccc summary {key}") + for key in ("cognitive", "cyclomatic"): + if not isinstance(summary.get(key), dict) or any(type(summary[key].get(field)) is not int or summary[key][field] < 0 for field in ("sum", "max", "median", "p90", "p95")): + raise MeasurementError(f"Invalid cccc summary {key}") + for file in report["files"]: + file["path"] = str(Path(file["path"]).relative_to(repo)) + if file["path"] not in paths: + raise MeasurementError(f"cccc reported a file outside the selected scope: {file['path']}") + for function in functions(file["functions"]): + for key in ("line", "cyclomatic", "cognitive"): + if type(function[key]) is not int or function[key] < (1 if key == "line" else 0): + raise MeasurementError(f"Invalid cccc function {key} in {file['path']}") + if "parse_error_files" in report["summary"]: + report["summary"]["parse_error_files"] = [str(Path(path).relative_to(repo)) for path in report["summary"]["parse_error_files"]] + return report, version + + +def measure_lizard(repo, paths, limitations): + lizard, duplicate_module, nesting_module, version = load_lizard() + supported = [name for name in paths if lizard.get_reader_for(str(repo / name))] + for name in sorted(set(paths) - set(supported)): + limitations.append({"path": name, "tool": "lizard", "reason": "unsupported source"}) + duplicates = duplicate_module.LizardExtension() + def nesting(tokens, reader): + return nesting_module.LizardExtension()(tokens, reader) + extensions = lizard.get_extensions([nesting, duplicates]) + records = {} + for info in lizard.analyze_files([str(repo / name) for name in supported], threads=1, exts=extensions): + name = str(Path(info.filename).relative_to(repo)) + depths = None + invalid_depths = False + if Path(name).suffix.lower() in {".py", ".pyw"}: + try: + depths = function_depths((repo / name).read_text(encoding="utf-8-sig"), name) + omitted = set(depths) - {f.start_line for f in info.function_list} + if omitted: + limitations.append({"path": name, "tool": "lizard", "reason": "functions omitted", "lines": sorted(omitted)}) + except (SyntaxError, UnicodeError, RecursionError) as error: + invalid_depths = True + limitations.append({"path": name, "tool": "python-ast", "reason": str(error)}) + rows = [] + for function in info.function_list: + row = {"name": function.name, "line": function.start_line, "end_line": function.end_line, + "nloc": function.nloc, "parameters": function.parameter_count} + if depths is not None: + if function.start_line in depths: + row["max_nesting"] = depths[function.start_line] + else: + limitations.append({"path": name, "tool": "python-ast", "reason": "unmatched function", "line": function.start_line}) + elif not invalid_depths: + row["max_nesting"] = int(function.max_nested_structures) + rows.append(row) + records[name] = rows + clones = [ + {"locations": [{"path": str(Path(part.file_name).relative_to(repo)), "line": part.start_line, "end_line": part.end_line} for part in group]} + for group in duplicates.get_duplicates(CLONE_TOKENS) ] - if len(same_name) == 1: - return same_name[0] - same_signature = [item for item in same_name if item["longName"] == function["longName"]] - if same_signature: - return min(same_signature, key=lambda item: abs(item["line"] - function["line"])) - if same_name: - return min(same_name, key=lambda item: abs(item["line"] - function["line"])) - return None - - -def metric_value( - value: int, - baseline: int | None, - band: str | None = None, - is_new: bool = False, -) -> dict[str, Any]: - result: dict[str, Any] = {"value": value} - if is_new: - result["baseline"] = "absent" - result["delta"] = "new" - elif baseline is not None: - result["baseline"] = baseline - result["delta"] = value - baseline - if band: - result["band"] = band - return result - - -def duplicate_pairs(groups: list[list[dict[str, Any]]]) -> dict[tuple[str, str], int]: - pairs: dict[tuple[str, str], int] = {} - for group in groups: - for left, right in itertools.combinations(group, 2): - key = tuple(sorted((left["file"], right["file"]))) - span = min( - left["endLine"] - left["line"] + 1, - right["endLine"] - right["line"] + 1, - ) - pairs[key] = max(pairs.get(key, 0), span) - return pairs - - -def duplicate_triggers( - candidate_groups: list[list[dict[str, Any]]], - base_groups: list[list[dict[str, Any]]], - changed: dict[str, str | None], - changed_lines: dict[str, list[tuple[int, int]]], - whole_repository: bool, - minimum_tokens: int, -) -> list[dict[str, Any]]: - base_pair_lengths = duplicate_pairs(base_groups) - results: list[dict[str, Any]] = [] - seen: set[tuple[tuple[str, int, int], ...]] = set() - - for group in candidate_groups: - touches_change = whole_repository or any( - snippet["file"] in changed - and intersects( - snippet["line"], - snippet["endLine"], - changed_lines.get(snippet["file"], []), - ) - for snippet in group - ) - if not touches_change: - continue - - state = "present" if whole_repository else None - baseline_lines: int | None = None - if not whole_repository: - for left, right in itertools.combinations(group, 2): - old_left = changed.get(left["file"], left["file"]) - old_right = changed.get(right["file"], right["file"]) - if old_left is None or old_right is None: - state = "new" - continue - base_key = tuple(sorted((old_left, old_right))) - candidate_span = min( - left["endLine"] - left["line"] + 1, - right["endLine"] - right["line"] + 1, - ) - prior_span = base_pair_lengths.get(base_key) - if prior_span is None: - state = "new" - elif candidate_span > prior_span and state != "new": - state = "expanded" - baseline_lines = prior_span - - if state is None: - continue - identity = tuple( - sorted((item["file"], item["line"], item["endLine"]) for item in group) - ) - if identity in seen: - continue - seen.add(identity) - item: dict[str, Any] = { - "state": state, - "minimumTokens": minimum_tokens, - "locations": group, - "reference": REFERENCES["duplication"], - } - if state == "new": - item["baseline"] = "absent" - item["delta"] = "new" - elif state == "expanded": - item["delta"] = "expanded" - if baseline_lines is not None: - item["baselineSpanLines"] = baseline_lines - results.append(item) - return results - - -def write_raw(payload: dict[str, Any]) -> str: - descriptor, path = tempfile.mkstemp(prefix="code-complexity-", suffix=".json") - with os.fdopen(descriptor, "w", encoding="utf-8") as stream: - json.dump(payload, stream, indent=2, sort_keys=True) - stream.write("\n") - return path - - -def parser() -> argparse.ArgumentParser: - result = argparse.ArgumentParser(description=__doc__) - result.add_argument("--repo", default=".", help="Git repository to measure") - result.add_argument("--base", help="Base revision for changed-code measurement") - result.add_argument( - "--whole-repository", - action="store_true", - help="Measure every supported production source file without a baseline", - ) - result.add_argument("--all", action="store_true", help="Include every normalized record") - result.add_argument("--cyclomatic-review", type=int, default=DEFAULTS["cyclomaticReview"]) - result.add_argument("--nloc-review", type=int, default=DEFAULTS["nlocReview"]) - result.add_argument( - "--nested-structures-review", - type=int, - default=DEFAULTS["nestedStructuresReview"], - ) - result.add_argument( - "--parameter-count-review", - type=int, - default=DEFAULTS["parameterCountReview"], - ) - result.add_argument("--duplicate-tokens", type=int, default=DEFAULTS["duplicateTokens"]) - return result - - -def main() -> int: - args = parser().parse_args() + clones.sort(key=lambda group: [(part["path"], part["line"]) for part in group["locations"]]) + return records, clones, float(duplicates.duplicate_rate() or 0), version + + +def leaf_name(name): + return re.split(r"\.|::", name)[-1] + + +def enrich(report, records, paths, limitations): + files = {file["path"]: file for file in report["files"]} + attached = 0 + for name in paths: + if name not in files: + limitations.append({"path": name, "tool": "cccc", "reason": "source not reported"}) + files[name] = {"path": name, "functions": []} + file = files[name] + if file.get("parse_errors"): + limitations.append({"path": name, "tool": "cccc", "reason": "parse errors", "errors": file["parse_errors"]}) + cccc_index, lizard_index = defaultdict(list), defaultdict(list) + for function in functions(file["functions"]): + cccc_index[(function["line"], leaf_name(function["name"]))].append(function) + for row in records.get(name, []): + lizard_index[(row["line"], leaf_name(row["name"]))].append(row) + unmatched = [] + for key, rows in lizard_index.items(): + targets = cccc_index.get(key, []) + if len(rows) == len(targets) == 1 and not file.get("parse_errors"): + targets[0]["lizard"] = {k: v for k, v in rows[0].items() if k not in {"name", "line"}} + attached += 1 + else: + unmatched.extend(rows) + if unmatched: + file["lizard_unmatched"] = unmatched + limitations.append({"path": name, "tool": "join", "reason": "Lizard functions retained separately", "count": len(unmatched)}) + missing = sum(len(targets) for key, targets in cccc_index.items() if key not in lizard_index) + if missing and name in records: + limitations.append({"path": name, "tool": "lizard", "reason": "cccc functions lack supporting measurements", "count": missing}) + report["files"] = [files[name] for name in sorted(files)] + return attached + + +def build_summary(report, records, clones, rate, attached): + rows = [row for file in records.values() for row in file] + lizard_summary = {"file_count": len(records), "function_count": len(rows), "attached_function_count": attached, + "unmatched_function_count": len(rows) - attached} + for key in ("nloc", "max_nesting", "parameters"): + values = [row[key] for row in rows if key in row] + lizard_summary[key] = {**distribution(values), "measured_function_count": len(values)} + lizard_summary["duplication"] = {"minimum_tokens": CLONE_TOKENS, "group_count": len(clones), "rate": rate} + report["summary"]["lizard"] = lizard_summary + cccc_rows = [function for file in report["files"] for function in functions(file["functions"])] + attention = {} + for key, (minimum, reference) in ATTENTION.items(): + population = cccc_rows if key in {"cognitive", "cyclomatic"} else rows + attention[key] = {"count": sum(row.get(key, -1) >= minimum for row in population), + "minimum": minimum, "reference": f"references/{reference}"} + attention["duplication"] = {"count": len(clones), "minimum_tokens": CLONE_TOKENS, "reference": "references/duplication.md"} + report["summary"]["attention"] = attention + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--repo", default=".", help="Git repository root") + parser.add_argument("--base", default="HEAD", help="Git revision used only to select changed files, default HEAD") + parser.add_argument("--cccc", help="Override the bundled executable with a supplied path") + parser.add_argument("paths", nargs="*", help="Explicit files relative to --repo, overrides changed-file selection") + args = parser.parse_args() try: - if args.whole_repository and args.base: - raise MeasurementError("--base and --whole-repository cannot be combined.") - if not args.whole_repository and not args.base: - raise MeasurementError("--base is required unless --whole-repository is set.") - thresholds = { - "cyclomaticReview": args.cyclomatic_review, - "nlocReview": args.nloc_review, - "nestedStructuresReview": args.nested_structures_review, - "parameterCountReview": args.parameter_count_review, - "duplicateTokens": args.duplicate_tokens, - } - if any(value < 1 for value in thresholds.values()): - raise MeasurementError("Every threshold must be a positive integer.") - + if sys.version_info < (3, 9): + raise MeasurementError("Python 3.9 or newer is required.") repo = Path(args.repo).resolve() - if not repo.is_dir(): - raise MeasurementError(f"Repository directory does not exist: {repo}") - git(repo, "rev-parse", "--show-toplevel") - head = git(repo, "rev-parse", "HEAD").decode().strip() - base = None - if args.base: - base = git(repo, "rev-parse", "--verify", f"{args.base}^{{commit}}").decode().strip() - - lizard, lizardns, duplicate_module, lizard_version = load_analyzer() - all_current_paths = current_paths(repo) - supported_current, _ = source_paths(all_current_paths, repo, lizard) - - if args.whole_repository: - changed: dict[str, str | None] = {path: None for path in supported_current} - changed_lines = { - path: [(1, max(1, sum(1 for _ in (repo / path).open("rb"))))] - for path in supported_current - } - unsupported_changed: list[str] = [] - else: - changed = changed_paths(repo, base or args.base) - changed_lines = { - path: line_ranges(repo, base or args.base, path, old_path is None) - for path, old_path in changed.items() - } - supported_changed, unsupported_changed = source_paths(changed, repo, lizard) - changed = {path: changed[path] for path in supported_changed} - changed_lines = {path: changed_lines[path] for path in supported_changed} - - candidate_functions, candidate_duplicates, candidate_duplicate_rate = analyze( - repo, - supported_current, - lizard, - lizardns, - duplicate_module, - thresholds["duplicateTokens"], - ) - - base_functions: list[dict[str, Any]] = [] - base_duplicates: list[list[dict[str, Any]]] = [] - base_duplicate_rate: float | None = None - if base: - with tempfile.TemporaryDirectory(prefix="code-complexity-base-") as directory: - base_root = Path(directory) - possible_base_paths = base_paths(repo, base) - supported_base, _ = source_paths(possible_base_paths, base_root, lizard) - extracted = extract_base(repo, base, supported_base, base_root) - base_functions, base_duplicates, base_duplicate_rate = analyze( - base_root, - extracted, - lizard, - lizardns, - duplicate_module, - thresholds["duplicateTokens"], - ) - - changed_functions = [ - function - for function in candidate_functions - if function["file"] in changed - and ( - args.whole_repository - or intersects( - function["line"], - function["endLine"], - changed_lines.get(function["file"], []), - ) - ) - ] - - band_counts = {"low": 0, "moderate": 0, "high": 0, "veryHigh": 0} - maxima = { - "cyclomaticComplexity": 0, - "nloc": 0, - "nestedStructures": 0, - "parameterCount": 0, - "tokenCount": 0, - } - function_triggers: list[dict[str, Any]] = [] - - for function in changed_functions: - metrics = function["metrics"] - band = cyclomatic_band(metrics["cyclomaticComplexity"]) - band_counts[band] += 1 - for metric in maxima: - maxima[metric] = max(maxima[metric], metrics[metric]) - - baseline_function = baseline_match( - function, - base_functions, - changed.get(function["file"]), - ) - baseline_metrics = baseline_function["metrics"] if baseline_function else {} - is_new = bool(base and baseline_function is None) - triggered: dict[str, Any] = {} - references: list[str] = [] - - if metrics["cyclomaticComplexity"] >= thresholds["cyclomaticReview"]: - triggered["cyclomaticComplexity"] = metric_value( - metrics["cyclomaticComplexity"], - baseline_metrics.get("cyclomaticComplexity"), - band, - is_new, - ) - references.append(REFERENCES["cyclomaticComplexity"]) - if metrics["nloc"] > thresholds["nlocReview"]: - triggered["nloc"] = metric_value( - metrics["nloc"], baseline_metrics.get("nloc"), is_new=is_new - ) - references.append(REFERENCES["nloc"]) - if metrics["nestedStructures"] > thresholds["nestedStructuresReview"]: - triggered["nestedStructures"] = metric_value( - metrics["nestedStructures"], - baseline_metrics.get("nestedStructures"), - is_new=is_new, - ) - references.append(REFERENCES["nestedStructures"]) - if metrics["parameterCount"] >= thresholds["parameterCountReview"]: - triggered["parameterCount"] = metric_value( - metrics["parameterCount"], - baseline_metrics.get("parameterCount"), - is_new=is_new, - ) - references.append(REFERENCES["parameterCount"]) - - if triggered: - function_triggers.append( - { - "file": function["file"], - "line": function["line"], - "endLine": function["endLine"], - "symbol": function["symbol"], - "metrics": triggered, - "tokenCount": metrics["tokenCount"], - "references": sorted(set(references)), - } - ) - - duplication_triggers = duplicate_triggers( - candidate_duplicates, - base_duplicates, - changed, - changed_lines, - args.whole_repository, - thresholds["duplicateTokens"], - ) - - scope = { - "base": base, - "candidate": f"working-tree@{head}", - "changedProductionFiles": len(changed), - "sourceFilesAnalyzed": len(supported_current), - "changedFunctionsAnalyzed": len(changed_functions), - "excludedChangedPaths": sorted( - path - for path in (all_changed_paths(repo, base or args.base) if base else {}) - if excluded(path) - ), - } - summary = { - "cyclomaticBands": band_counts, - "maxima": maxima, - "observedCloneGroups": len(candidate_duplicates), - "duplicateRate": candidate_duplicate_rate, - "triggeredFunctions": len(function_triggers), - "triggeredCloneGroups": len(duplication_triggers), - } + if Path(git(repo, "rev-parse", "--show-toplevel").strip()).resolve() != repo: + raise MeasurementError("--repo must be the Git repository root.") + paths, scope = select_files(repo, args.paths, args.base) + identity = content_id(repo, paths) + report, cccc_version = measure_cccc(repo, paths, args.cccc or bundled_cccc()) limitations = [] - if unsupported_changed: - limitations.append( - { - "kind": "unsupported-language", - "paths": sorted(unsupported_changed), - } - ) - - tool = { - "name": "lizard", - "version": lizard_version, - "cloneDetector": { - "name": "lizard-duplicate", - "version": lizard_version, - }, - } - raw_payload = { - "schema": SCHEMA_VERSION, - "tool": tool, - "scope": scope, - "thresholds": thresholds, - "functions": candidate_functions, - "duplicates": candidate_duplicates, - "duplicateRate": candidate_duplicate_rate, - "baseFunctions": base_functions, - "baseDuplicates": base_duplicates, - "baseDuplicateRate": base_duplicate_rate, - "limitations": limitations, - } - raw_artifact = write_raw(raw_payload) - attention = bool(function_triggers or duplication_triggers) - status = "incomplete" if limitations else "attention" if attention else "clear" - output: dict[str, Any] = { - "schema": SCHEMA_VERSION, - "tool": tool, - "status": status, - "scope": scope, - "thresholds": thresholds, - "summary": summary, - "triggers": { - "functions": function_triggers, - "duplicates": duplication_triggers, - }, - "rawArtifact": raw_artifact, - } - if limitations: - output["limitations"] = limitations - if args.all: - output["records"] = { - "functions": candidate_functions, - "duplicates": candidate_duplicates, - } - print(json.dumps(output, indent=2, sort_keys=True)) + records, clones, rate, lizard_version = measure_lizard(repo, paths, limitations) + attached = enrich(report, records, paths, limitations) + build_summary(report, records, clones, rate, attached) + if content_id(repo, paths) != identity or select_files(repo, args.paths, args.base)[0] != paths: + raise MeasurementError("Selected source changed during measurement. Rerun on the current candidate.") + report.update({ + "schema": 4, "status": "partial" if limitations else "complete", + "scope": {**scope, "content_id": identity}, + "tools": {"cccc": cccc_version, "lizard": lizard_version, "python": sys.version.split()[0], + "nesting": "Python AST for Python, lizard-ns for other languages"}, + "duplicates": clones, "limitations": limitations, + }) + descriptor, destination = tempfile.mkstemp(prefix="code-complexity-", suffix=".json") + with os.fdopen(descriptor, "w", encoding="utf-8") as stream: + json.dump(report, stream, indent=2) + stream.write("\n") + print(json.dumps({"schema": report["schema"], "status": report["status"], "summary": report["summary"], + "scope": {"mode": scope["mode"], "file_count": len(paths), "content_id": identity}, + "tools": report["tools"], "limitation_count": len(limitations), "report": destination}, indent=2)) return 0 - except MeasurementError as error: - print( - json.dumps( - { - "schema": SCHEMA_VERSION, - "status": "incomplete", - "error": str(error), - }, - indent=2, - sort_keys=True, - ) - ) + except (MeasurementError, OSError, ValueError, KeyError, TypeError, ImportError, subprocess.TimeoutExpired) as error: + print(json.dumps({"status": "failed", "error": str(error)}, indent=2)) return 2 diff --git a/skills/measure-code-complexity/scripts/python_nesting.py b/skills/measure-code-complexity/scripts/python_nesting.py new file mode 100644 index 0000000..afd22ed --- /dev/null +++ b/skills/measure-code-complexity/scripts/python_nesting.py @@ -0,0 +1,52 @@ +"""Measure maximum syntactic control nesting per Python function.""" + +from __future__ import annotations + +import ast + + +CONTROLS = {'If', 'For', 'AsyncFor', 'While', 'Try', 'TryStar', 'With', 'AsyncWith', 'Match', 'IfExp'} +FUNCTIONS = (ast.FunctionDef, ast.AsyncFunctionDef) +COMPREHENSIONS = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp) + + +def control_depth(node: ast.AST, depth: int = 0) -> int: + if isinstance(node, FUNCTIONS): + headers = [node.args, *node.decorator_list, *getattr(node, 'type_params', [])] + if node.returns is not None: + headers.append(node.returns) + return max([depth, *(control_depth(header, depth) for header in headers)]) + if isinstance(node, COMPREHENSIONS): + # Each generator nests in the preceding generator and its filters. + maximum = depth + level = depth + for generator in node.generators: + level += 1 + maximum = max(maximum, control_depth(generator.iter, level)) + if generator.ifs: + level += 1 + maximum = max(maximum, level) + for condition in generator.ifs: + maximum = max(maximum, control_depth(condition, level)) + for field in ('elt', 'key', 'value'): + if hasattr(node, field): + maximum = max(maximum, control_depth(getattr(node, field), level)) + return maximum + nested = depth + int(type(node).__name__ in CONTROLS) + maximum = nested + for child in ast.iter_child_nodes(node): + # An elif belongs to the same choice as its preceding if. + is_elif = (isinstance(node, ast.If) and child in node.orelse + and isinstance(child, ast.If) and child.col_offset == node.col_offset) + child_depth = depth if is_elif else nested + maximum = max(maximum, control_depth(child, child_depth)) + return maximum + + +def function_depths(source: str, filename: str) -> dict[int, int]: + tree = ast.parse(source, filename=filename) + return { + node.lineno: max((control_depth(statement) for statement in node.body), default=0) + for node in ast.walk(tree) + if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) + } diff --git a/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md b/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md index f3c85cd..e67ce54 100644 --- a/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md +++ b/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md @@ -1,8 +1,10 @@ # Third-Party Notices -The measurement script loads these unmodified Python wheels directly from this directory: +The measurement script uses these bundled releases: + +- cccc 1.7.0, under the MIT [licence](cccc/LICENSE). Unmodified release archives cover macOS and Linux ARM64/x64 and Windows x64. `cccc/manifest.json` records archive and extracted executable SHA-256 values. The helper selects the host archive, verifies it and caches only its executable in the system temporary directory. No installation or runtime download occurs. Release archives retain upstream README and licence notices. Source and release provenance are recorded in the refactor research report outside this runtime bundle. - Lizard 1.24.0, checksum `a688bc607a891ff4a7836826f25742dc9c1bf648da3075dbd495e199e8848602`. Retain its [license](licenses/lizard/LICENSE.txt) and the [Apache License 2.0](licenses/lizard/APACHE-2.0.txt) referenced by licensed source headers. - Pygments 2.19.2, checksum `86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b`. Retain its [license](licenses/pygments/LICENSE) and [authors](licenses/pygments/AUTHORS). -The wheels remain subject to their included upstream notices and disclaimers. +These releases remain subject to their included upstream notices and disclaimers. diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/LICENSE b/skills/measure-code-complexity/scripts/vendor/cccc/LICENSE new file mode 100644 index 0000000..52ff4bc --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/cccc/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Taiki Kawakami (a.k.a moznion) https://moznion.net + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-aarch64-apple-darwin.tar.gz b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-aarch64-apple-darwin.tar.gz new file mode 100644 index 0000000..49e7afc Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-aarch64-apple-darwin.tar.gz differ diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-aarch64-unknown-linux-musl.tar.gz b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-aarch64-unknown-linux-musl.tar.gz new file mode 100644 index 0000000..0d6707f Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-aarch64-unknown-linux-musl.tar.gz differ diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-apple-darwin.tar.gz b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-apple-darwin.tar.gz new file mode 100644 index 0000000..606d931 Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-apple-darwin.tar.gz differ diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-pc-windows-msvc.zip b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-pc-windows-msvc.zip new file mode 100644 index 0000000..911cc29 Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-pc-windows-msvc.zip differ diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-unknown-linux-musl.tar.gz b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-unknown-linux-musl.tar.gz new file mode 100644 index 0000000..fccdffc Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/cccc/cccc-v1.7.0-x86_64-unknown-linux-musl.tar.gz differ diff --git a/skills/measure-code-complexity/scripts/vendor/cccc/manifest.json b/skills/measure-code-complexity/scripts/vendor/cccc/manifest.json new file mode 100644 index 0000000..c74c580 --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/cccc/manifest.json @@ -0,0 +1,35 @@ +{ + "version": "1.7.0", + "targets": { + "aarch64-apple-darwin": { + "archive": "cccc-v1.7.0-aarch64-apple-darwin.tar.gz", + "archive_sha256": "babeea26b5304e41ed503b799a59924bbe90b44806bd2ad176e643159fb7213b", + "member": "cccc", + "binary_sha256": "9008bcf0ecf2f31ca07dff460316229d84234a169e995d715d11844afa2e594b" + }, + "aarch64-unknown-linux-musl": { + "archive": "cccc-v1.7.0-aarch64-unknown-linux-musl.tar.gz", + "archive_sha256": "f775a19ebd58fc7a4cd64769b8d442425d8afde66207386db04eb87747ed75b8", + "member": "cccc", + "binary_sha256": "4891105e6b0d00e4eec1e8e8ed6f06dcdf728f4e7df0a9e7a268b61aa14a39ef" + }, + "x86_64-apple-darwin": { + "archive": "cccc-v1.7.0-x86_64-apple-darwin.tar.gz", + "archive_sha256": "ac3edcd5e64c26933b18952df350401e1379220208cb78a414d8d4c3f1879d2e", + "member": "cccc", + "binary_sha256": "ffec2528e41111a3255f867c37f666e00b2793c5e7bfb26a9ec6635d7c1ccc46" + }, + "x86_64-pc-windows-msvc": { + "archive": "cccc-v1.7.0-x86_64-pc-windows-msvc.zip", + "archive_sha256": "c9af68a559087d0d3c7c995bd19e718b091175c5f85a2dea38ecfc8803e49f35", + "member": "cccc.exe", + "binary_sha256": "29b78152c99dbe83d747e57bb91e1b0e1532b888a6edbd9c1dc20339582db6c6" + }, + "x86_64-unknown-linux-musl": { + "archive": "cccc-v1.7.0-x86_64-unknown-linux-musl.tar.gz", + "archive_sha256": "75d2fb5486238eeb40a80fec2de8fe5075e6ce567b6741a56fa511ed2082e45a", + "member": "cccc", + "binary_sha256": "4f88c49816485b008b352680938e92de868ae82d9ffba48e12e1ed8a577b1509" + } + } +} diff --git a/skills/modular-design/SKILL.md b/skills/modular-design/SKILL.md index 935991c..b0c2cb4 100644 --- a/skills/modular-design/SKILL.md +++ b/skills/modular-design/SKILL.md @@ -1,85 +1,27 @@ --- name: modular-design -description: Teaches structural design through information hiding, deep modules, cohesive ownership, stable interfaces, and change locality. Use when writing or assessing code, boundaries, contracts, dependencies, seams, or change propagation. -metadata: - type: teaching -disable-model-invocation: true +description: Design simple interfaces over deep modules when a code change creates or alters ownership, domain rules, or dependencies. --- -# Modular Design +# Modular design -Teaches a caller to make the smallest coherent change through deep modules whose owned knowledge and likely changes remain local. +Give callers a simple contract that hides substantial domain knowledge. Choose the smallest coherent design that satisfies the confirmed behaviour. **Information hiding** and **deep modules** reduce the code and context callers need. -## Process +## Inputs -### 1. Fix the structural basis +Start from the confirmed requirements and affected interfaces. Inspect their owners and consumers. Existing code shows current structure, not a requirement to preserve it. A module can be a function, object or feature. Its interface includes inputs, outcomes, errors, effects, ordering and invariants callers must understand. -Use the caller's confirmed behaviour, outcome, repository guidance, domain language, architecture decisions, relevant source, contracts, and tests. Inspect only evidence that is missing or stale. Follow explicit project authorities and established language and framework idioms when they conflict with this baseline. +## Method -Treat a **module** as any cohesive capability with an interface and implementation: a function, object, component, package, process, service, or tier-spanning slice. Treat its **interface** as everything callers must know, including operations, data, invariants, ordering, errors, configuration, effects, and material performance characteristics. Do not equate modules with files, classes, layers, or deployment units. +1. **Start with the caller.** Write realistic usage before choosing signatures or classes. State what the caller needs to accomplish and observe. Read [design examples](references/design-examples.md) when introducing an interface or judging whether a boundary hides enough knowledge. +2. **Choose one owner per decision.** Put each rule, representation, state and sequence with the capability that owns it. Callers ask that owner for derived facts or complete operations. Repeated eligibility checks across consumers belong in the domain owner. Group code that changes for the same reason. Separate independent responsibilities. +3. **Design a deep module.** Keep the public contract small and cohesive. Hide storage layouts, vendor protocols and internal stages. `reservation.confirm(command)` can own the transition and effect ordering. Separate public `validate`, `markConfirmed`, `save` and `publish` operations make callers learn that sequence. Depth means knowledge hidden, not a long call chain or a large class. +4. **Earn every abstraction.** Keep direct local code when it is already clear. Add a boundary for substantial hidden knowledge, real variation or an existing external dependency. Apply **YAGNI**. A language interface, class, factory or separate file must remove more caller burden than it adds. Read [design techniques](references/techniques.md) for a concrete dependency, invariant, state or ownership problem. +5. **Design it twice for material choices.** For a consequential new or changed public interface, owner or dependency direction, compare two viable shapes. Show caller usage, hidden decisions and how an evidenced change propagates through each. Choose the smaller coherent contract. A routine change inside an established owner needs no design ceremony. +6. **Trace locality.** Walk a plausible requirement change through the owner and its consumers. Revise designs that repeat a decision, expose internals or require callers to coordinate hidden stages. Use [refactoring and deletion techniques](../code-cleanup/references/refactorings.md) when reshaping existing code. Invoke [$code-cleanup](../code-cleanup/SKILL.md) when an independent cleanup review is needed. -Use confirmed behaviour and applicable quality requirements as constraints on ownership, boundaries, and contracts. Do not redefine those requirements during structural design. +## Finish -### 2. Assign each decision to one owner +Return the chosen owner, caller contract, hidden decisions and locality trace. Include a material alternative and trade-off when step 5 applies. Leave implementation and independent review to the caller. -Name the behaviour and every rule, invariant, protocol, representation, sequence, side effect, or framework decision it introduces or changes. Keep each with its natural existing owner when that owner remains coherent; otherwise create the smallest boundary that owns the complete concern. An owner has the knowledge and authority needed to uphold the decision, not merely the nearest file or conventional technical layer. - -Represent each material decision once. Co-locate elements that change for the same current, evidenced reason. Separate elements when their responsibilities and axes of change differ. Prefer domain and capability boundaries over uniform file sizes or technical-layer symmetry. - -Keep derived knowledge behind the owner of its source representation. When another module needs a fact such as a total, classification, eligibility, or transition derived from owned state, use or add a domain-meaningful owner operation instead of making the caller traverse that state. Let the caller derive it only when the representation is deliberately public and the derivation belongs to the caller's own policy. - -Check these contrasts: - -- **Local rule:** put a pricing threshold in the pricing policy that decides it. **Leaked rule:** repeat it in a controller, job, validator, and their tests. -- **Owned derivation:** ask an order for `totalWeightGrams()` when it owns line weights and quantities. **Leaked derivation:** make delivery, fulfilment, and reporting each traverse order lines to reconstruct that fact. -- **Cohesive size:** keep a large parser together when its grammar and invariants change as one concern. **Fragmented size:** split it only to satisfy a line or class count, making one grammar change cross several files. -- **Damaging coordinator:** reconsider even a short coordinator when it knows every participant's order, data shape, and error handling; brevity does not make scattered knowledge cohesive. - -### 3. Design a deep interface - -Apply **information hiding** and **deep modules**. Give callers substantial cohesive capability through a comparatively simple, domain-meaningful contract. Minimise what callers must know rather than method count. Hide representations, mechanisms, sequencing, framework details, and policies that callers do not need. Make required inputs, outcomes, failures, ordering, and effects explicit. - -Keep the contract narrower and more stable than the decisions behind it without combining unrelated knowledge merely to appear deep. A design interface does not require a language `interface`, base class, wrapper, or extra file. - -Check these contrasts: - -- **Deep:** `reservation.confirm(command)` owns validation, state transition, persistence sequencing, and the confirmation outcome. **Shallow:** callers invoke `validate`, `markConfirmed`, `save`, and `publish` in the required order. -- **Hidden vendor protocol:** an adapter accepts checkout terms and maps vendor fields, units, and expected failures. **Leaked protocol:** controllers and policies know `vendorAmount`, vendor error classes, and response codes. -- **Owned boundary:** retain a layer that translates, authorises, applies policy, preserves compatibility, observes, or coordinates an application conversation. **Pass-through:** absorb a layer whose only act is forwarding the same arguments and result to another contract. - -### 4. Keep the change coherent and earned - -Make the least production, test, and supporting change that completely delivers the confirmed behaviour and leaves its knowledge local. Fewest lines or files is not the goal. Permit a bounded enabling refactor only when the behaviour cannot fit coherently without it; alter no more surrounding structure than the behaviour needs. - -Keep a stable local concrete dependency direct. Add an abstraction only for current evidence of meaningful variation, isolated observation, replacement, staged migration, a volatile external mechanism, a material technology or ownership boundary, or separation of stable policy from mechanism. Reuse an existing extension point only when its contract fits the present behaviour. Do not add hypothetical implementations, options, generic services, interface-per-class, universal repositories, plugin systems, or unrelated cleanup. - -Use objects for cohesive identity, state, lifecycle, and invariants when they fit. Use functions, closures, structural types, modules, components, composition, and framework primitives when they preserve the same ownership with less machinery. Use inheritance only for genuine substitutability or a required framework extension. - -### 5. Compare material structural choices - -When introducing or substantially changing a public interface, module boundary, seam, or dependency direction, load [Design It Twice](references/DESIGN-IT-TWICE.md). Produce at least two genuinely different responsibility or contract designs, compare them, and select the smallest design supported by current evidence. Routine work that fits an established coherent boundary proceeds directly. - -The caller produces and selects the alternatives inside its own workflow. Do not dispatch a design workflow, require parallel agents, or turn the comparison into a separate artefact unless the caller's outcome requires one. - -### 6. Apply only triggered techniques - -Classify triggers from the evidence already loaded, then read only the smallest applicable reference. An ordinary ownership choice, one domain vocabulary, one conditional, or the mere possibility of future change is not a trigger: - -- Load [Dependency Techniques](references/DEPENDENCY-TECHNIQUES.md) when stable policy directly knows a volatile mechanism; a material technology or ownership boundary needs translation; controlled substitution, observation, replacement, or migration is required; composition competes with inheritance; or polymorphic substitutability is in question. -- Load [Domain Techniques](references/DOMAIN-TECHNIQUES.md) only when one term has evidenced competing meanings or rules, domain language and observed change patterns disagree with the current boundary, or co-location versus extraction remains a material choice after the ownership analysis. Do not load it for a single coherent domain model or an ordinary file-placement choice. -- Load [Decision and Effect Techniques](references/EFFECT-TECHNIQUES.md) only when substantial deterministic policy across multiple cases or transitions is entangled with I/O, time, mutable state, or framework lifecycle effects. Do not load it for one calculation or conditional merely because the surrounding operation performs I/O. - -Do not load references to search for a reason to use a technique. Use one fitting mechanism when triggers overlap. Treat SOLID and named patterns as diagnostic vocabulary, not mandatory architecture; treat smells and metrics only as prompts to investigate a concrete mechanism and consequence. - -### 7. Trace locality - -Trace one plausible current-project change through the proposed owner, interface, consumers, implementation, and tests. Prefer a change suggested by requirements, integrations, repository history, or present volatility over an imagined future. - -Reconsider the design when the same decision remains duplicated, elements that always change together are split, an owner changes mostly for unrelated reasons, callers still coordinate hidden sequencing, or one conceptual change requires scattered edits. Do not substitute file size, class count, method count, churn, coupling scores, complexity thresholds, or speculative agent-context savings for this trace. - -Keep the owner, caller-visible contract, hidden decisions, locality trace, triggered technique or material comparison, and unresolved structural uncertainty explicit in the caller's workflow. - -## Rules - -- Prefer project evidence over generic architecture advice. -- Preserve the complete confirmed behaviour while improving structure; do not trade correctness or scope for aesthetic purity. +**Done only when** the confirmed behaviour has coherent ownership, callers need no avoidable internal knowledge, and each new abstraction earns its cost. Report unresolved contractual or structural decisions before dependent implementation. diff --git a/skills/modular-design/agents/openai.yaml b/skills/modular-design/agents/openai.yaml index d97ee31..0e76feb 100644 --- a/skills/modular-design/agents/openai.yaml +++ b/skills/modular-design/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Modular Design' - short_description: 'Design deep modules with local change' -policy: - allow_implicit_invocation: false + short_description: 'Hide domain knowledge behind simple interfaces' diff --git a/skills/modular-design/references/DEPENDENCY-TECHNIQUES.md b/skills/modular-design/references/DEPENDENCY-TECHNIQUES.md deleted file mode 100644 index 0ab6087..0000000 --- a/skills/modular-design/references/DEPENDENCY-TECHNIQUES.md +++ /dev/null @@ -1,48 +0,0 @@ -# Dependency Techniques - -Load only for a triggered dependency, technology boundary, seam, composition, or substitutability decision. A contract in design does not require a language `interface`. - -## Invert volatile mechanism knowledge - -Apply **dependency inversion** when stable domain or application policy directly knows a materially volatile framework, device, vendor, persistence, transport, or delivery mechanism. Define the smallest policy-owned contract in policy language and make the mechanism satisfy it. - -- **Good:** invoicing policy asks a `TaxRateSource` for the rate and the vendor adapter owns authentication, wire fields, and response mapping. -- **Bad:** invoicing imports vendor request types and switches on vendor status codes, or adds an interface that repeats one stable local calculator without changing dependency knowledge. - -Cost: an owned contract and composition wiring must be maintained. Keep a stable local concrete dependency direct when inversion creates only interface-per-class indirection. - -## Isolate a material boundary - -Apply **ports and adapters** when an application-purpose conversation must remain independent of a material external technology or ownership boundary, isolated execution, replacement, staged migration, or multiple implementations. State the port in the application's language; let adapters translate UI, persistence, network, vendor, or test technology. Framework types stay at framework-owned edges. - -- **Good:** `PlaceOrder` accepts an application command and returns an application outcome while HTTP and database adapters translate at the edges. -- **Bad:** wrap every framework call, mirror a vendor SDK method-for-method, or add a generic provider registry for one fixed integration. - -Cost: translation, wiring, and sometimes duplicated boundary types. A concrete adapter without a language interface can still be the right port boundary when it hides the protocol and no separate runtime contract is earned. - -## Add a controlled seam - -Add a **seam** when substitution, observation, replacement, or staged migration requires behaviour to vary without editing the calling location. Use the smallest enabling point: a parameter, callback, collaborator, provider, module export, composition-root binding, or framework facility. - -- **Good:** inject a clock where expiry policy needs deterministic time. -- **Bad:** introduce factories and provider interfaces around every deterministic local function in case tests might mock it. - -Cost: another variation point callers and maintainers must understand. Prefer direct behaviour when it is local, stable, and observable through its supported outcome. - -## Prefer composition and delegation - -Use composition or delegation when a capability can be assembled from independently owned behaviours without claiming an is-a relationship. Keep delegation deep: the composing owner must add policy, translation, sequencing, or a simpler capability rather than merely repeat another contract. - -- **Good:** a `Checkout` delegates tax calculation and payment authorisation while owning their ordering and checkout outcome. -- **Bad:** `PaymentService.process()` only forwards to `PaymentProcessor.process()` with identical inputs, outputs, and responsibility. - -Cost: extra navigation and wiring. Absorb a delegation layer that owns no decision. - -## Require genuine substitutability - -Use inheritance or polymorphism only when every subtype can honour the complete base contract for all supported callers without strengthened preconditions, weakened outcomes, surprising effects, or type tests. Prefer composition for optional behaviour or shared implementation that does not form a stable substitutable concept. - -- **Good:** supported storage adapters honour the same explicit read/write/error contract. -- **Bad:** `ReadOnlyRepository extends Repository` but throws from inherited `save`, forcing callers to inspect its concrete type. - -Cost: base-contract evolution constrains every subtype. A required framework extension is valid when its lifecycle contract is honoured, even when composition would otherwise be preferred. diff --git a/skills/modular-design/references/DESIGN-IT-TWICE.md b/skills/modular-design/references/DESIGN-IT-TWICE.md deleted file mode 100644 index 4d4443a..0000000 --- a/skills/modular-design/references/DESIGN-IT-TWICE.md +++ /dev/null @@ -1,28 +0,0 @@ -# Design It Twice - -Load this reference only for a material new or substantially changed public interface, module boundary, seam, or dependency direction. - -## Form two real designs - -Describe at least two alternatives that differ in ownership, caller knowledge, contract, or dependency direction. Renaming, moving the same class, changing interface syntax, or comparing a credible design with an obvious straw design does not count. - -Keep each alternative only detailed enough to decide. For each, state: - -- which module owns the rule, representation, sequence, and effects; -- what callers must know and do; -- what the interface promises, including failure and effects; -- which dependencies point toward which owner; -- how tests observe the promised behaviour; and -- how one plausible evidenced change propagates. - -Compare interface depth, caller burden, cohesion, locality, dependency direction, testability, transition cost, and speculative machinery. Select the smallest coherent design supported by current evidence; record the losing alternative's material disadvantage and any uncertainty that could reverse the choice. - -## Contrast: delivery quote boundary - -Suppose checkout needs a delivery quote from one current carrier. - -**Design A — concrete checkout adapter:** `DeliveryQuotes` depends directly on `FastShipDeliveryQuotes`, which translates FastShip fields and failures into checkout terms. This hides the vendor protocol with no language interface. It is preferable when one implementation is approved, the concrete adapter is replaceable at the composition root, and tests can observe policy without a distinct runtime contract. - -**Design B — policy-owned port:** `DeliveryQuotes` depends on a checkout-owned `DeliveryQuoteSource`; `FastShipDeliveryQuoteSource` implements it. This adds a separate stable contract. It is preferable when isolated execution, multiple implementations, staged replacement, or an ownership boundary currently requires the policy to remain independent of the concrete adapter. - -Both designs isolate vendor translation. Selecting B merely because another carrier might exist someday is speculative; selecting A when application policy must directly import vendor types leaves the boundary incomplete. diff --git a/skills/modular-design/references/DOMAIN-TECHNIQUES.md b/skills/modular-design/references/DOMAIN-TECHNIQUES.md deleted file mode 100644 index 7b65338..0000000 --- a/skills/modular-design/references/DOMAIN-TECHNIQUES.md +++ /dev/null @@ -1,32 +0,0 @@ -# Domain Techniques - -Load only when domain meanings, observed change contours, or co-location and extraction are materially in question. - -## Separate competing meanings - -Apply **bounded contexts** when the same term has competing meanings, rules, lifecycles, or representations. Keep one ubiquitous language and model inside each evidenced context; translate explicitly at their boundary. - -- **Good:** Sales `Customer` owns prospects and purchasing eligibility while Support `Customer` owns service entitlement, with an explicit identity translation. -- **Bad:** one universal `Customer` accumulates nullable sales, billing, fulfilment, and support state, so every change affects unrelated callers. - -Cost: translation and explicit context ownership. Do not create bounded contexts merely because departments or folders have different names. - -## Follow conceptual contours - -Apply **conceptual contours** when domain language and observed axes of change reveal a more natural capability grain than current technical layers or uniform class sizes. Keep entity identity, state, invariants, and cohesive behaviour together. Use a standalone domain service only for a significant process that belongs naturally to no entity or value object. - -- **Good:** an `Allocation` owns quantity invariants and release behaviour that always change together. -- **Bad:** split `AllocationValidator`, `AllocationUpdater`, and `AllocationRules` by technical action, making one invariant change cross all three. - -Cost: a domain-shaped module may be larger or cross conventional layer boundaries. That is acceptable when its contract remains clear and changes stay local. - -## Co-locate or extract for evidenced locality - -Co-locate code when it shares one owner and changes for the same evidenced reason. Extract when a complete sub-concern has a distinct contract, reuse by real consumers, independent volatility, or enough hidden knowledge to repay navigation. - -- **Good co-location:** keep a component's one-use rendering helper beside the component while they evolve together. -- **Bad extraction:** move every small helper into a global utilities module, coupling unrelated capabilities to a grab bag. -- **Good extraction:** isolate a tax-jurisdiction rule used by checkout and invoicing behind one policy-owned contract. -- **Bad co-location:** duplicate that rule in both consumers to avoid adding a file. - -Cost: extraction adds naming, navigation, and a contract; co-location can overload an owner when change reasons diverge. Decide from ownership and propagation rather than size. diff --git a/skills/modular-design/references/EFFECT-TECHNIQUES.md b/skills/modular-design/references/EFFECT-TECHNIQUES.md deleted file mode 100644 index c29c327..0000000 --- a/skills/modular-design/references/EFFECT-TECHNIQUES.md +++ /dev/null @@ -1,14 +0,0 @@ -# Decision and Effect Techniques - -Load only when substantial deterministic decisions are entangled with I/O, time, mutable state, or framework lifecycle effects. - -## Form a functional core and imperative shell - -Apply **functional core, imperative shell** when explicit input values can drive substantial deterministic policy while a narrow edge performs I/O, time access, mutation, or framework integration. The core returns decisions or intended effects; the shell obtains inputs, executes effects, and maps failures. - -- **Good:** a renewal function receives subscription state and `now`, then returns `renew`, `expire`, or `no-op`; a job handler loads state, calls it, and performs the selected effect. -- **Bad:** policy reads the system clock, database, queue, and configuration throughout nested branches, so every case requires effectful setup and policy changes alter orchestration. - -Preserve stateful ownership when identity, lifecycle, effect ordering, transactions, or invariant enforcement is intrinsic. Do not turn an application into a bag of pure functions with an unencapsulated shell. - -Cost: explicit values and decision types cross the core boundary, and the shell must translate effect failures honestly. Use the technique only when the deterministic policy is substantial enough to repay that contract. diff --git a/skills/modular-design/references/design-examples.md b/skills/modular-design/references/design-examples.md new file mode 100644 index 0000000..6c69be4 --- /dev/null +++ b/skills/modular-design/references/design-examples.md @@ -0,0 +1,87 @@ +# Design examples + +These original examples show how to reduce caller knowledge. Judge the entire contract, including effects and failures. Shorter code that conceals a needed guarantee is not a better interface. + +## Ask the owner for a fact + +Delivery quotes and warehouse labels both need the order's total weight. Each currently knows the order's storage layout and weight calculation. + +```ts +// Before, repeated in both consumers. +const grams = order.rows.reduce( + (sum, row) => sum + row.product.shipping.grams * row.quantity, + 0, +); + +// After, each consumer asks the order. +const grams = order.totalWeightGrams(); +``` + +The order owns quantities and product weights, so it owns this derived fact. Its private implementation can change without edits to delivery or labels. Keep the delivery provider's size limit in delivery policy. Moving that independent rule into the order would mix ownership. + +## Complete the operation behind the interface + +A reservation must validate availability, transition state, commit it, then publish confirmation. Consumers currently repeat the sequence. + +```ts +// Before. +reservation.checkAvailability(command); +reservation.markConfirmed(command); +await reservation.save(); +await reservation.publishConfirmation(); + +// After. +const outcome = await reservation.confirm(command); +``` + +Define the outcome and failure contract, including what happens if publication fails after commitment. The reservation capability owns sequencing. The caller handles the documented outcome. Keep lower-level operations public only when supported consumers independently need their contracts. A one-line wrapper that forwards `confirm` unchanged would hide no additional decision. + +## Translate a vendor at the boundary + +Checkout currently interprets the payment provider's statuses and optional wire fields. + +```ts +// Before, checkout knows the provider protocol. +const response = await sdk.createPaymentIntent(providerPayload); +if (response.status === 'requires_action') { + return { kind: 'challenge', url: response.next_action.redirect_to_url.url }; +} + +// After, checkout knows its own payment contract. +const outcome = await payments.authorise({ orderId, amount, currency }); +if (outcome.kind === 'challenge') + return { kind: 'challenge', url: outcome.url }; +``` + +The payment module owns payload construction, provider statuses and error translation. Its domain outcomes must represent real success, rejection and challenge states. One concrete adapter can do this. A generic provider registry, factory and interface per SDK method add machinery without hiding more knowledge. Keep an adapter even with one consumer when it isolates this substantial protocol. + +## Encode the invariant in the representation + +A completion flag and optional timestamp require callers to reason about combinations that should never exist. + +```ts +// Before. +type Work = { completed: boolean; completedAt?: Date }; + +// After. +type Work = { kind: 'open' } | { kind: 'complete'; completedAt: Date }; +``` + +The new model removes the contradictory completed-without-time state. When the timestamp alone expresses the contract, use `completedAt: Date | null` and derive completion instead. Keep a plain list for summation because an empty list sums to zero. Introducing a non-empty list type there would solve no partial operation. + +## Choose ownership before file count + +`InvoiceLoader`, `InvoiceValidator` and `InvoiceFormatter` all know one invoice grammar. A grammar change requires all three files and their pass-through interfaces. A single invoice module with private parsing helpers can hide that knowledge behind `readInvoice(bytes)`. + +Conversely, a billing module that mixes invoice grammar with a carrier's delivery protocol has two independent reasons to change. Give the carrier translation its own contract. Splitting by a real decision removes unrelated knowledge. Splitting each parsing phase into a class merely spreads one decision. + +## Compare viable designs + +Checkout needs quotes from one current carrier. Both designs must hide its wire format. + +| Design | Caller contract | What it hides | When it earns its cost | +| -------------------------------------- | ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| Concrete `DeliveryQuotes` module | `quote(destination, parcel)` | Carrier protocol and failure mapping | One current integration with a replaceable composition point | +| Checkout-owned quote port plus adapter | The same domain operation | Protocol plus independence from the concrete adapter | Real isolated execution, concurrent implementations or an active migration requires substitution | + +Trace a change to the carrier's response format. It should affect the adapter alone in both shapes. The port wins only when the extra dependency boundary serves a current requirement. A possible second carrier someday does not earn it. diff --git a/skills/modular-design/references/techniques.md b/skills/modular-design/references/techniques.md new file mode 100644 index 0000000..b153cf0 --- /dev/null +++ b/skills/modular-design/references/techniques.md @@ -0,0 +1,43 @@ +# Design techniques + +Choose a technique for an observed ownership or dependency problem. A pattern name does not justify extra code. Use the repository's language and framework idioms. Existing-code transformations live in [code cleanup](../../code-cleanup/references/refactorings.md). + +## Information hiding and single responsibility + +Own a coherent body of domain knowledge behind one interface. Apply the **single responsibility principle** to reasons for change, not one class per operation. A parser can own loading, validation and decoding when they protect one grammar. A module serving unrelated domain policies needs separate owners. + +Keep related state and behaviour together. Consumers should ask `order.totalWeightGrams()` rather than repeat knowledge of its line representation. Keep consumers' independent policies with those consumers. Follow an actual change trace before deciding to combine or separate owners. + +## Dependency inversion and ports and adapters + +Apply **dependency inversion** when domain policy knows a volatile external mechanism. State the smallest contract in the policy's language. An adapter translates the external protocol into that contract. + +For example, invoicing asks a rate source for a jurisdiction's tax rate. Its vendor adapter owns authentication, response fields and provider errors. Invoicing importing the vendor's response type leaks that protocol. Mirroring every SDK operation behind an interface preserves the leak and adds navigation. + +Use **ports and adapters** where an application operation must remain independent of delivery or persistence technology. A concrete module can hide the mechanism without a language interface. Add a substitution seam only when current execution, replacement or integration requires it. A clock parameter can make expiry policy deterministic. A factory hierarchy around every local helper adds needless variation. + +## Constructive modelling and one source of truth + +Use **algebraic data types** or the language's equivalent to make invalid combinations unrepresentable. Model meaningful variants, exhaust them, and derive duplicated state. Parse untrusted input at the real boundary. Internal type annotations alone provide no runtime validation. + +Choose structures that remove actual branching. A lookup table suits fixed mappings. A state machine suits valid lifecycle transitions. A reducer can give state updates one owner. Keep a simple exhaustive conditional when it already expresses the rule directly. Do not create a class hierarchy just to disguise that conditional. + +Derive types and registrations from their authoritative schema or definition where practical. Two hand-maintained lists of the same variants create coordinated edits. Keep one source and derive the other, or enforce agreement mechanically when independent definitions are required. + +## Functional core, imperative shell + +Separate substantial deterministic decisions from I/O when explicit values give them a clear contract. A renewal policy can receive subscription state and the current time and return a decision. A narrow job handler loads the inputs and applies that decision. + +Keep transactional ownership and effect ordering together. A trivial comparison does not need a separate policy class. A shell that exposes every intermediate mutation to callers loses the invariant the separation should protect. + +## Composition and substitutability + +Prefer **composition** for assembled capabilities. Each collaborator must own meaningful policy or mechanism. A checkout that coordinates payment and stock can be deep. A service forwarding the same call to another service owns nothing new. + +Apply the **Liskov substitution principle** when using inheritance. Every subtype must honour supported preconditions, outcomes, errors and effects. A read-only repository that inherits `save` and throws violates its writable base contract. Use a narrower contract or composition. Required framework inheritance remains valid when its lifecycle contract is honoured. + +## Bounded contexts and conceptual contours + +Use **bounded contexts** when the same word has different meanings and invariants. Sales eligibility and support entitlement may have separate customer models with explicit identity translation. A universal customer full of optional fields couples unrelated policies. Different folder names alone do not establish different meanings. + +Use **conceptual contours** to keep identity, state and invariants together at a natural domain grain. A standalone domain service earns its place for a process that belongs to no existing entity or value object. A generic utilities module collecting unrelated rules gives them no coherent owner. diff --git a/skills/pull-request/SKILL.md b/skills/pull-request/SKILL.md index 3981cc5..d823791 100644 --- a/skills/pull-request/SKILL.md +++ b/skills/pull-request/SKILL.md @@ -1,19 +1,25 @@ --- name: pull-request -description: Publishes the current branch as one concise verified pull request. Use when the branch is ready for external review. -metadata: - type: utility -disable-model-invocation: true +description: Publish a branch with a Conventional Commit title and succinct description when asked to open or update its pull request. --- -# Pull Request +# Pull request -Publishes the complete branch for review without advancing it further. +Publish the complete branch as **one matching open pull request** with a relevant title and description. -## Process +## Inputs -Assign the entire process below to one fresh agent with the user's request and repository path. Have it invoke `$commit` when eligible uncommitted work belongs to the branch, compare the whole branch with its base, then use the repository's native tools to push without rewriting history before creating or updating one pull request. +Take the branch to publish from the request or current Git state. Resolve the host, target repository, named head branch, and base before publication. Use an existing matching PR's base and readiness unless the request changes them. Ask only when inspection leaves a material ambiguity. -Use one **Conventional Commit** title for the complete outcome. Write the first body paragraph as three short sentences covering what, why, and how. Add a short testing paragraph only when existing tests provide material behavioural evidence; describe the behaviour covered and any material gap, not the suite, coverage, metrics, or publication-time execution, and do not run tests. +## Method -Have the fresh agent read back the title, URL, head, base, state, and published revision. Return the title and URL, adding only a material blocker or excluded work when necessary, and retain only that result. Stop without reviewing, merging, releasing, or deploying. +1. Read [$commit](../commit/SKILL.md) for the title conventions. Invoke it whenever uncommitted changes exist. Continue only after it completes. +2. Inspect the complete branch diff against its base, including earlier commits. Invoke [$write-prose](../write-prose/SKILL.md) for a Conventional Commit title summarising the full change and a succinct description covering **what changed, why, and the resulting behaviour**. Keep required PR template fields and material evidence or limitations. Reuse valid checks and distinguish local evidence from remote CI status. +3. Push the intended branch without rewriting remote history. Reuse a matching open PR and check its title and description against the full diff and these requirements. Update either when stale or noncompliant. Otherwise create one PR, ready by default. Preserve an existing PR's readiness unless directed to change it. After an uncertain mutation result, read host state before retrying to avoid duplicates. +4. Read back the PR's URL, title, body, head, base, readiness, and published revision. Verify that the revision matches the intended local head and that the metadata describes the complete change. + +## Finish + +Return the PR title and URL with any blocker or material validation limitation. + +**Done only when** all uncommitted work is recorded and the matching open PR contains the intended revision, base, readiness, title, and description. Report failures with remaining work preserved. Stop before review, merge, release, deployment, or ongoing CI monitoring. diff --git a/skills/pull-request/agents/openai.yaml b/skills/pull-request/agents/openai.yaml index a117e71..ebd93c8 100644 --- a/skills/pull-request/agents/openai.yaml +++ b/skills/pull-request/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Pull Request' - short_description: 'Publish one concise verified pull request' -policy: - allow_implicit_invocation: false + short_description: 'Open or update a PR with a succinct change description' diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 9134b21..5ffe3e1 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -1,49 +1,28 @@ --- name: research -description: Investigates a material subject against high-trust sources and writes a trusted cited report. Use when a material question needs durable external evidence. -metadata: - type: utility -disable-model-invocation: true +description: Produce a durable cited report when a user or calling agent requests research into a question, subject, package, or claim. --- # Research -Investigates a material subject in a fresh agent and hands back a trusted report for the consumer to synthesize. +Delegate **desk research** to a fresh agent and return an accessible, verified report. Keep source gathering outside the caller's context. -## Process +If explicitly assigned as the investigator, read [the investigator procedure](references/investigation.md) and perform it directly. Otherwise follow the caller method below. -### 1. Fix the subject and scope +## Inputs -Use the request and caller context to state what the research is for and what it covers. Resolve discoverable scope without questioning. Ask the user only when an ambiguity could materially change the investigation. Treat every invocation as standalone; do not inspect or maintain previous research reports. +Take the research question or subject from the request. Ask only when missing information would materially change the investigation. -Use `docs/research/` as the default output directory unless the caller specifies another destination. Keep the investigation within authorised read and report-write boundaries. +Save reports in `docs/research/` unless told otherwise. Preserve existing reports unless updating or replacing them was requested. -### 2. Start the fresh investigation +## Method -Start exactly one fresh agent with the fixed subject and scope, relevant task-local evidence, available source tools, output destination, source rules, report template, and stopping rule. Do not supply a desired answer. The fresh agent owns discovery, source appraisal, thematic organisation, report writing, and report verification as one evidence chain; it does not delegate the investigation again. +1. **Brief a fresh agent.** Give it this skill's path, the request, relevant context, source access, and authorised reads and writes in a self-contained brief. Pass a user hypothesis as a claim to investigate. Start with fresh context rather than inheriting the conversation. +2. **Keep the handoff small.** The investigator owns gathering, writing, and source verification. Request only the report path and material limitations or blockers. Relay necessary user questions through the caller. Continue independent work while it runs, then wait for completion before handing back. +3. Check that the saved report exists. Use its content for downstream work without repeating source gathering or verification unless a specific concern warrants it. -Require the fresh agent to: +## Finish -- identify the material claims and areas needed to cover the scope, then select source types capable of establishing each one; -- prefer primary, original, official, or owning sources; use an authoritative secondary source when it is itself appropriate to the claim, and trace its material claims to original evidence where possible; -- treat authority as claim-relative: an originator can establish what a practice says, but that alone does not prove its effectiveness; -- corroborate material claims through genuinely independent evidence routes where available, and seek credible disagreement, contrary evidence, and important gaps; -- appraise what each source can establish, including its authority, validity, currency, applicability, completeness, incentives, and consistency with underlying evidence; -- distinguish sourced fact from material inference and distinguish missing evidence from evidence against; and -- stop when the scope has adequate high-trust coverage, conflicts and limitations are recorded, and further searching is unlikely to add materially different findings. +Return the report path and material limitations or blockers. The caller owns downstream decisions, implementation, publication, and external changes. -### 3. Write the report - -Create a new standalone Markdown report using [the research report template](assets/research-report-template.md). Organise `Findings` by human-readable themes rather than by source. Cite every material claim with numbered references such as `[1]`, reuse a source's number, and provide the matching numbered links under `Sources`. - -Write for human readers. Use natural language, varied sentence length, short coherent paragraphs, descriptive subheadings, and restrained bold, italics, lists, or tables where they improve comprehension. Identify material inference explicitly. - -Keep the five template sections. `Scope` only explains what the research was for and what subject or information need it covered. Give each conflict and limitation its own paragraph; state `None identified.` when applicable. - -### 4. Verify the trusted report - -Require the fresh agent to re-read the finished report and verify that every material claim is supported by its cited source; citations and source numbers resolve; links open to the identified evidence; independent routes are not duplicate retellings of one upstream claim; conflicts, limitations, and material inferences are visible; all five sections are present; and the writing is coherent and easy to navigate. It corrects report defects before returning. - -## Handoff - -Return only the finished report path to the user or caller. Retain none of the investigation transcript in the calling thread and require no duplicate caller verification. Stop after handoff; the consumer owns every overall synthesis, conclusion, recommendation, decision, and downstream mutation. +**Done only when** the investigator has met its completion gate and the saved report path has been returned. Report a missing prerequisite and its dependent work without claiming completion. diff --git a/skills/research/agents/openai.yaml b/skills/research/agents/openai.yaml index 1412093..76cfab7 100644 --- a/skills/research/agents/openai.yaml +++ b/skills/research/agents/openai.yaml @@ -1,6 +1,4 @@ interface: display_name: 'Research' - short_description: 'Research a subject into a trusted cited report' - default_prompt: 'Use $research to investigate this subject in a fresh agent and write a trusted cited report.' -policy: - allow_implicit_invocation: false + short_description: 'Delegate research and save an accessible cited report' + default_prompt: 'Use $research to investigate this subject and save a cited report.' diff --git a/skills/research/assets/research-report-template.md b/skills/research/assets/research-report-template.md index fefe963..154fc84 100644 --- a/skills/research/assets/research-report-template.md +++ b/skills/research/assets/research-report-template.md @@ -1,23 +1,23 @@ # {Research title} -## Scope +## Answer -{Describe what the research was for and the subject or information need it covered.} +{Answer the question or summarise the key findings. Include decisive qualifications and citations.} -## Findings +## Scope -### {Descriptive theme} +{State the question or subject, purpose, boundaries, and research date.} -{Present the evidence in approachable prose. Cite each material claim with its numbered source, for example [1], and identify material inference explicitly.} +## Findings -## Conflicts +### {Heading that names the finding} -{Give each material conflict its own paragraph, with citations. Write "None identified." when applicable.} +{Explain the finding and its implications. Cite material claims with descriptive source links or numbered references. Identify inference. Use comparisons or examples where they help the reader.} -## Limitations +## Conflicts and limitations -{Give each material evidence gap, access constraint, unresolved uncertainty, or relevant research limitation its own paragraph. Write "None identified." when applicable.} +{Include only material disagreement, evidence gaps, access limits, or unanswered questions. Explain the relevant search and what each limit changes. Omit this section when empty.} ## Sources -1. [Source title](https://example.com/source) — {author, publisher, or owning organisation} +1. [{Source title}](https://example.com/source). {Author or responsible organisation. Include relevant dates, versions, or file locations.} diff --git a/skills/research/references/investigation.md b/skills/research/references/investigation.md new file mode 100644 index 0000000..5f9289d --- /dev/null +++ b/skills/research/references/investigation.md @@ -0,0 +1,18 @@ +# Investigation + +Produce one accessible report answering the brief. Stay within authorised source reads and report writes. Perform this assignment directly. + +## Method + +1. **Frame the investigation.** Identify every material question and claim needed to cover the scope. A claim is material when its accuracy could change the answer, recommendation, or confidence. Resolve discoverable facts directly. Return necessary user-held questions to the caller before dependent work. +2. **Trace and appraise evidence.** Use **citation chaining** to seek the original evidence for every material factual claim and attempt verification in its full context. Read the source rather than rely on search snippets. Use **lateral reading** to check relevant expertise and credibility beyond the source's own account. Assess evidence provenance, methods, currency, applicability, completeness, and interests for the particular claim. Primary status or publisher reputation alone does not establish reliability. +3. Permit secondary analysis or synthesis when that appraisal supports its use. Verify material underlying claims where possible. If an original remains inaccessible after reasonable alternative access attempts, cite the account actually read, disclose the verification limit, and qualify the conclusion. Assess a synthesis's methods and limitations without claiming to have audited every underlying study. Official documentation establishes an organisation's published contract or claim. Comparative effectiveness needs suitable independent evidence. For example, a vendor's “fastest” claim establishes its advertising, not measured superiority. +4. **Challenge and cover.** Seek credible contrary evidence and genuinely independent evidence routes. Repeated accounts of one original do not corroborate it. Resolve discrepancies where possible. Otherwise retain the conflict and its effect on the answer. Continue while meaningful gaps remain investigable. Stop when every scoped question has an answer or an explicit unresolved finding and further searching is unlikely to materially change the result. Missing evidence is distinct from evidence against. +5. **Write the report.** Invoke [$write-prose](../../write-prose/SKILL.md) with the brief, findings, sources, and audience. Use [the report template](../assets/research-report-template.md) unless the caller supplied a format. Adapt the layout to the subject, retaining an answer-first structure, scope and research date, organised findings, material conflicts and limitations, and references. Cite material claims near their evidence, including in the summary. Identify inference and ground requested recommendations in findings. Omit empty sections. +6. **Verify and save.** Check the actual report against the sources read. Correct unsupported claims, misleading certainty, unresolved citation targets, and links that do not identify the evidence. Include relevant dates, versions, or precise locations where they affect interpretation. Save the report. + +## Finish + +Return only the report path and material limitations or blockers. + +**Done only when** every scoped question has a supported answer or an explicit unresolved finding explaining the search and its implications, claims and references have been checked, and the report is saved. A missing prerequisite remains a blocker. Keep any partial report clearly labelled incomplete. diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md deleted file mode 100644 index f7723d6..0000000 --- a/skills/review-architecture/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: review-architecture -description: Reviews a whole codebase for high-impact evidence-backed modular-design improvements and writes an interactive HTML report. Use for architecture or structural maintainability reviews. -metadata: - type: performer -disable-model-invocation: true ---- - -# Review Architecture - -Finds the most consequential current opportunities to improve a codebase's modular structure and explains them in one interactive HTML report. - -## Process - -### 1. Establish whole-codebase evidence - -Inspect the request, repository guidance, root `PRODUCT.md` and `GLOSSARY.md`, applicable ADRs, current revision, and starting worktree state. Treat the whole repository as the review scope while honouring explicit exclusions. Map its capabilities and inspect the source, tests, contracts, schemas, configuration, and operational evidence needed to understand current structure. Exclude dependencies, generated output, vendored code, and obsolete paths from recommendation coverage. - -Inspect relevant Git history after mapping the repository. Use repeated cross-file changes and hotspots as supporting evidence and ranking signals without excluding quieter areas. Distinguish project authority, current observation, inference, and unknowns. - -Apply `$modular-design` to the authorities and current evidence. Invoke `$research` only when a material candidate depends on external framework, platform, or technical evidence that the repository cannot establish; read its report before deciding whether the candidate qualifies. - -### 2. Retain only top-level candidates - -Require each candidate to have precise current repository evidence, a credible structural cause, a material present benefit, and visible trade-offs or uncertainty. State only the recommended structural direction, why it matters, and what it improves. Claim only improvements caused by that structural direction; do not imply that it establishes correctness, safety, or another quality it cannot demonstrate. Reject cosmetic cleanup, unsupported smell labels, speculative abstractions, and changes whose benefit is minor or hypothetical. - -Keep only the highest-impact qualifying candidates. Use no fixed count. Order them by explicit qualitative judgement of present consequence, evidence, likely benefit, and feasibility; preserve that fixed order and identify the top recommendation. Zero candidates is a valid result. Record reviewed coverage and meaningful non-qualifying areas so absence of recommendations remains trustworthy. - -### 3. Write the interactive report - -Write only `docs/architecture/YYYYMMDD-full-codebase-architecture-review.html`, using `-2`, `-3`, and later numeric suffixes when a same-day path exists unless replacement was explicit. Copy and complete [the report template](assets/report-template.html). Escape repository-derived text before placing it in HTML and remove every template marker. - -Keep each candidate's recommendation, reason, and improvement always visible. Put exact file and history evidence, trade-offs, and uncertainty in one native expandable section. Do not add filters, reordering, scores, detailed target interfaces, file-by-file changes, migration steps, test prescriptions, tickets, or an implementation plan. - -Add a current-versus-recommended visual only when it makes the structural relationship materially easier to understand. Design it specifically for that candidate with accessible HTML or inline SVG; add another CDN library only when it clearly improves the explanation. Omit a weak, generic, or decorative visual. - -### 4. Verify and stop - -Run the bundled `scripts/validate-report.js` with Bun and the report path. Re-read the report against the fixed order and current evidence; verify every cited repository path and material claim, the top recommendation, coverage, limitations, HTML escaping, and absence of leftover markers. Recheck the revision for material drift and confirm that only the report changed apart from pre-existing work. Do not open the report or perform rendered visual review. - -Return the report path, ordered candidate titles or the zero-candidate result, reviewed revision, invoked research, verification, and limitations. Stop without changing implementation or project authorities, elaborating a detailed design, creating specifications or tickets, committing, or publishing. diff --git a/skills/review-architecture/agents/openai.yaml b/skills/review-architecture/agents/openai.yaml deleted file mode 100644 index 21441f7..0000000 --- a/skills/review-architecture/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Review Architecture' - short_description: 'Find the biggest structural improvements' -policy: - allow_implicit_invocation: false diff --git a/skills/review-architecture/assets/report-template.html b/skills/review-architecture/assets/report-template.html deleted file mode 100644 index 0274bc8..0000000 --- a/skills/review-architecture/assets/report-template.html +++ /dev/null @@ -1,213 +0,0 @@ - - - - - - %%PROJECT_NAME%% architecture review - - - - - -
-
-

- Architecture review · %%REVIEW_DATE%% -

-

- %%PROJECT_NAME%% -

-

- %%OUTCOME_SUMMARY%% -

-
-
-
Reviewed revision
-
- %%REVISION%% -
-
-
-
Recommendations
-
%%CANDIDATE_COUNT%%
-
-
-
Scope
-
- Whole codebase%%SCOPE_EXCLUSIONS%% -
-
-
-
- - - -
-
-
-

- Prioritised shortlist -

-

- Highest-impact opportunities -

-
- -
- -
- -
-

- Recommendation 01 · top recommendation -

-

- %%CANDIDATE_TITLE%% -

-
-
-
- Recommendation -
-
- %%RECOMMENDATION%% -
-
-
-
- Why it matters -
-
- %%WHY_IT_MATTERS%% -
-
-
-
- What it improves -
-
- %%WHAT_IT_IMPROVES%% -
-
-
- - - -
- - Evidence and trade-offs - - -
-
-

- Evidence -

-
%%EVIDENCE%%
-
-
-

- Trade-offs and uncertainty -

-
%%TRADEOFFS%%
-
-
-
-
- %%ADDITIONAL_CANDIDATES_OR_ZERO_RESULT%% -
-
- -
-

- Review record -

-

- Coverage and limitations -

-
-
-

Reviewed

-
%%REVIEWED_COVERAGE%%
-
-
-

- Limitations -

-
%%LIMITATIONS%%
-
-
-
-
- - diff --git a/skills/review-architecture/scripts/validate-report.js b/skills/review-architecture/scripts/validate-report.js deleted file mode 100644 index 10a0a01..0000000 --- a/skills/review-architecture/scripts/validate-report.js +++ /dev/null @@ -1,99 +0,0 @@ -#!/usr/bin/env bun - -import fs from 'node:fs'; -import path from 'node:path'; - -const reportPath = process.argv[2]; -const errors = []; - -if (!reportPath) { - console.error('Usage: bun scripts/validate-report.js '); - process.exit(2); -} - -const absolutePath = path.resolve(reportPath); -if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { - errors.push(`Report not found: ${absolutePath}`); -} - -let html = ''; -if (!errors.length) html = fs.readFileSync(absolutePath, 'utf8'); - -const normalized = absolutePath.split(path.sep).join('/'); -if ( - !normalized.includes('/docs/architecture/') || - path.extname(absolutePath) !== '.html' -) { - errors.push('Report must be an HTML file under docs/architecture/.'); -} -if ( - !/^\d{8}-full-codebase-architecture-review(?:-\d+)?\.html$/.test( - path.basename(absolutePath), - ) -) { - errors.push( - 'Report filename must follow the dated full-codebase convention.', - ); -} - -const required = [ - ['HTML document', //i], - ['language', /]*\blang=/i], - ['UTF-8 metadata', /]*charset=["']?utf-8/i], - ['responsive viewport', /]*name=["']viewport["']/i], - [ - 'Tailwind browser CDN', - /cdn\.jsdelivr\.net\/npm\/@tailwindcss\/browser@4/, - ], - [ - 'deferred Alpine CDN', - /]*\bdefer\b[^>]*alpinejs@3\.x\.x\/dist\/cdn\.min\.js/i, - ], - ['review root', /\bdata-architecture-review\b/], - ['reviewed revision', /\bdata-reviewed-revision\b/], - ['coverage', /\bdata-coverage\b/], -]; - -for (const [label, pattern] of required) { - if (!pattern.test(html)) errors.push(`Missing ${label}.`); -} - -if (/%%[A-Z0-9_-]+%%/.test(html)) - errors.push('Unresolved template marker remains.'); - -const candidates = [ - ...html.matchAll(/]*\bdata-recommendation=["'](\d+)["']/gi), -]; -const numbers = candidates.map((match) => Number(match[1])); -if (numbers.some((number, index) => number !== index + 1)) { - errors.push( - 'Recommendation numbers must be contiguous and in fixed document order.', - ); -} - -if (candidates.length) { - if (!/\bdata-top-recommendation\b/.test(html)) - errors.push('Missing top recommendation.'); - for (const marker of [ - 'data-recommendation-summary', - 'data-field="recommendation"', - 'data-field="why"', - 'data-field="improves"', - 'data-evidence', - 'data-tradeoffs', - ]) { - if (!html.includes(marker)) - errors.push(`Missing candidate field: ${marker}.`); - } -} else if (!/\bdata-zero-result\b/.test(html)) { - errors.push('A zero-candidate report must contain data-zero-result.'); -} - -if (errors.length) { - for (const error of errors) console.error(`- ${error}`); - process.exit(1); -} - -console.log( - `Report valid: ${absolutePath} (${candidates.length} recommendations)`, -); diff --git a/skills/review-pull-request/SKILL.md b/skills/review-pull-request/SKILL.md index 7f563e8..9c5029a 100644 --- a/skills/review-pull-request/SKILL.md +++ b/skills/review-pull-request/SKILL.md @@ -1,17 +1,23 @@ --- name: review-pull-request -description: Reviews a supplied pull request through independent specification and engineering-standards assessment. Use when a pull request needs a read-only independent report. -metadata: - type: router -disable-model-invocation: true +description: Review a pull request through code-review when the user supplies a PR identifier and requests a review. --- -# Review Pull Request +# Review a pull request -Routes one fixed pull request through `$code-review` and returns its independent findings unchanged. +Return `$code-review`'s result for the supplied pull request. Keep the workflow **read-only**. -## Process +## Inputs -Resolve the supplied pull-request identifier against the current repository unless another repository is named. Use native host metadata to fix its repository, number or URL, and exact base and head revisions. Return the exact blocker when the pull request is ambiguous or inaccessible. +Take a PR URL or number from the request. Use the current repository for a bare number unless the request names another repository. -Invoke `$code-review` with that fixed pull-request candidate and a read-only boundary. Return its result unchanged. +## Method + +1. Resolve host metadata to a unique repository and exact base and head revisions. Make the PR's merge-base-to-head diff and source available for review. +2. Load and invoke [$code-review](../code-review/SKILL.md) for that PR diff, passing any supplied behavioural authority. + +## Finish + +Return `$code-review`'s result unchanged. + +**Done only when** the PR is resolved and `$code-review` has completed. If resolution or review is blocked, return the exact blocker. diff --git a/skills/review-pull-request/agents/openai.yaml b/skills/review-pull-request/agents/openai.yaml index f2d504f..14d35c4 100644 --- a/skills/review-pull-request/agents/openai.yaml +++ b/skills/review-pull-request/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Review Pull Request' - short_description: 'Return a read-only pull-request review' -policy: - allow_implicit_invocation: false + short_description: 'Review a PR through code-review and return its result' diff --git a/skills/specify-feature/SKILL.md b/skills/specify-feature/SKILL.md index fed97ba..0145dc9 100644 --- a/skills/specify-feature/SKILL.md +++ b/skills/specify-feature/SKILL.md @@ -1,43 +1,26 @@ --- name: specify-feature -description: Creates a decision-complete specification for one feature. Use when a high-level feature request or capability needs collaborative definition before ticket creation. -metadata: - type: performer -disable-model-invocation: true +description: Specify and document one software feature when its behaviour and consequential technical decisions need definition or a durable specification. --- -# Specify Feature +# Specify feature -Turns one high-level feature description into one user-confirmed specification containing both feature intent and the selected buildable solution. +Produce a confirmed, **decision-complete** specification for one feature. Preserve enough intent, solution and rationale for ticket planning in a fresh conversation. -## Process +## Inputs -### 1. Build shared understanding +Take the feature from the request and its supplied context, including confirmed discussion. Read relevant project guidance, linked authorities and current-system evidence. -Inspect the request and the project evidence relevant to the feature. Resolve discoverable facts before asking the user, and distinguish evidence of the current system from intended future behaviour. +## Method -Invoke `$elicit-with-context` with the relevant evidence and unresolved decision whenever material user-held information or a decision is needed. Use its confirmed synthesis as authority for the feature direction. +1. **Prepare coverage.** Read [feature discovery](references/discovery.md) and [the specification template](assets/specification-template.md) before mapping the decision tree. Resolve discoverable facts through inspection or [$research](../research/SKILL.md). +2. **Elicit intent.** Invoke [$elicit-with-context](../elicit-with-context/SKILL.md) for the feature's scoped behaviour and constraints, using the discovery guidance. Use **goal-oriented use cases** and **Example Mapping** to connect flows, rules, examples and open questions. +3. **Settle the consequential solution.** Resolve choices that change observable behaviour, shared contracts, state ownership, safeguards, migration, verification or ticket dependencies. Invoke [$modular-design](../modular-design/SKILL.md) for material ownership and interface choices. Record the selected approach, load-bearing contracts, reasons and relevant rejected alternatives. Leave reversible internal coding choices and the per-slice implementation plan to tickets. Reopen intent when design exposes a gap. +4. **Check the complete specification.** Check rules against concrete acceptance examples and inherited constraints. Supply feature intent and the consequential solution to the active dialogue for confirmation. +5. **Write and connect.** Invoke [$write-prose](../write-prose/SKILL.md) with confirmed decisions, evidence and template. Follow project document conventions, defaulting to `docs/features//specification.md`. Link precise authorities and give referenced requirements stable IDs. When a matching product-index entry exists, fill its specification link. Preserve existing ticket checklists during revisions and report affected tickets when a decision changes. -Invoke `$research` when durable external evidence is needed to resolve the feature. Use its report as evidence, not as authority for a product or solution decision. +## Finish -### 2. Make the feature decision-complete +Re-read the saved specification for faithful decisions, complete scoped behaviour, observable acceptance, consequential solution rationale and valid links. Return its path, index update, checks and material limitations. Stop before ticket creation or implementation. -Establish **feature intent** before selecting the **solution**, and visibly reopen the affected intent when solution work exposes a behavioural gap. Use the [Feature Specification Template](assets/specification-template.md) as a coverage guide rather than a checklist: depth follows ambiguity, risk, external obligation and what ticket decomposition needs. - -Use goal-oriented use cases to connect actors to complete outcomes. Add triggers, preconditions, alternatives, failures and recovery where they reveal material behaviour. Use concrete context-event-outcome scenarios only where they make a rule, boundary or acceptance outcome testable through the application's interface or another stable observable boundary. Do not add user stories when they contribute no further meaning. - -Keep feature intent independent of internal implementation. Put consequential system-specific choices in the selected solution: enough responsibility, boundary, contract, data, integration, failure, quality, migration, operational and verification detail to constrain implementation, but not files, classes, framework wiring, exhaustive tests or ticket breakdown. Invoke `$modular-design` when a material structural choice needs resolving. - -Resolve every decision that could change scope, observable behaviour, acceptance or the material solution. An uncertainty may remain only when ticket decomposition is still safe; record its evidence, consequence, affected decisions and the condition or later user-agent step that will resolve it. Do not invent team roles, owners, approval bodies or third-party coordination. - -### 3. Write the specification - -Once shared understanding covers the complete feature, create `docs/features//specification.md` from the template. Record only decisions established with the user and evidence-supported facts, keeping feature intent and selected solution visibly distinct. Preserve the stable section spine, omit immaterial conditional content and link supporting product, context, decision, research, design and current-system evidence rather than duplicating it. - -Use stable semantic identifiers only where they make later reference and traceability clearer. Add a concise Mermaid diagram when a state model, interaction, boundary or runtime relationship is materially easier to understand visually. - -### 4. Verify and stop - -Re-read the finished document against the established decisions and cited evidence. Check that it describes one coherent feature; states each rule and decision once; covers the material use cases, adverse paths, qualities and acceptance boundaries; keeps acceptance observable; distinguishes intent from solution; traces consequential solution elements to their reason; and represents uncertainty honestly. - -The specification is ready when `$create-tickets` can decompose it without inventing product behaviour or selecting a material solution. Report the path, evidence used, verification performed and any non-blocking uncertainty. Do not create tickets or implement the feature. +**Done only when** contextual elicitation and applicable design work are complete, and the saved document permits ticket planning without inventing behaviour or choosing a consequential solution. Explicitly delegated coding choices may remain. Report any unmet prerequisite and dependent work instead of declaring readiness. diff --git a/skills/specify-feature/agents/openai.yaml b/skills/specify-feature/agents/openai.yaml index 27fdbe8..81ea128 100644 --- a/skills/specify-feature/agents/openai.yaml +++ b/skills/specify-feature/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Specify Feature' - short_description: 'Create one decision-complete feature specification' -policy: - allow_implicit_invocation: false + short_description: 'Define feature behaviour and consequential design' diff --git a/skills/specify-feature/assets/specification-template.md b/skills/specify-feature/assets/specification-template.md index a400d49..49d62b3 100644 --- a/skills/specify-feature/assets/specification-template.md +++ b/skills/specify-feature/assets/specification-template.md @@ -1,128 +1,48 @@ # {Feature name} -> **Authority:** This document owns the approved intent and selected solution for one feature. It is ready for ticket decomposition only when its readiness statement is satisfied. + - +## Overview and scope -## Feature overview +{Problem, beneficiary, desired outcome, current context and intended change. Link the originating request or product feature when available. State inclusions, exclusions and success conditions.} -{Orient the reader with the feature, its source request or capability, current context, intended beneficiaries, and concise outcome.} +## Behaviour -## Problem, outcomes, and success measures +### Actors and use cases -{State the evidenced problem or opportunity, desired user or product outcomes, and only applicable measures with their source, baseline, direction or threshold, and horizon when known.} +{Actors, permissions and goals. For each material use case, state trigger, preconditions, main flow, successful result, alternatives, failures, recovery and guarantees on unsuccessful exit. Include relevant system-initiated events.} -## Scope and non-goals +### Rules and requirements -### In scope +- **REQ-01:** {One unambiguous rule or requirement, including rationale where it affects interpretation.} -- {Included feature outcome or observable responsibility.} +{Add state or decision tables when transitions or combinations matter. Define material data meanings, validation, defaults, timing, visibility and interactions. Link applicable product-wide requirements precisely.} -### Non-goals +### Acceptance examples -- {Excluded adjacent behaviour and the boundary it preserves.} +#### {Scenario name} -## Actors, goals, and use cases +- **Covers:** {Requirement IDs} +- **Given:** {Relevant initial state and concrete inputs} +- **When:** {Action or event} +- **Then:** {Observable result, including material state changes and forbidden effects} -### {ACT-01 — Actor or beneficiary} +{Cover material happy, boundary, denial, failure and recovery cases. State general quality or acceptance conditions that examples alone cannot express.} -{Goal and value sought from this feature.} +## Consequential solution -### {UC-01 — Use-case name} +{Selected approach, responsibilities and state ownership, public and shared contracts, important data shapes and invariants, integrations, failure handling, migration and operational requirements. Include only material aspects.} -- **Actor:** {Primary actor.} -- **Trigger:** {Observable event that starts the use case.} -- **Preconditions:** {Material conditions, if any.} -- **Successful outcome:** {Externally observable completion.} -- **Alternatives and exceptions:** {Only material refusal, adverse, recovery, or edge paths.} +{Explain load-bearing choices, relevant rejected alternatives and trade-offs. Link existing ADRs instead of restating their rationale. Identify the stable boundaries and evidence that can verify behaviour. Use a precise contract sketch or diagram where it communicates a decision better than prose.} -## Feature intent +## Dependencies and remaining uncertainty -### Requirements and rules +{External and existing-system dependencies, assumptions and risks with evidence, consequences and resolution conditions. Explicitly identify delegated implementation choices.} -- **REQ-01 — {Requirement name}:** {One necessary, unambiguous, verifiable normative statement.} +## Evidence and readiness -### States and transitions +{Precise links to inspected sources and research. State why scoped behaviour and consequential design are settled sufficiently for ticket planning, and any limits.} - +## Tickets -### Experience and design requirements - - - -### Quality and external constraints - - - -### Scenarios and acceptance - -#### SC-01 — {Scenario name} - -- **Given:** {Observable starting context.} -- **When:** {Actor action or external event.} -- **Then:** {User-, assistive-technology-, contract-, or operating-interface outcome.} - -**Covers:** {REQ-01 and any distinct acceptance identifiers evidenced by this scenario.} - -#### Acceptance conditions - - - -- **ACC-01:** {Observable acceptance boundary stated once.} - -## Selected solution - -### Design drivers and current context - -{Link the requirements, constraints, accepted decisions, and inspected current-system forces that shape the solution. Distinguish current evidence from selected direction.} - -### Strategy and material decisions - -{State the selected coherent approach and only the alternatives or trade-offs needed to understand a consequential choice.} - -### Responsibilities and boundaries - -{Describe affected capabilities, owned knowledge, contracts, dependency direction, and enabling changes without a file or class inventory. Use a small Mermaid context or runtime diagram when it clarifies the design.} - -### Interfaces and data contracts - - - -### Data and lifecycle - - - -### Integrations and failure handling - - - -### Cross-cutting and operational design - - - -### Verification seams - -{Identify the public or stable contract boundaries and evidence capable of establishing the selected behaviour. Do not prescribe an exhaustive test inventory.} - -## Dependencies, assumptions, risks, and unresolved items - - - -- **DEP-01 — {Dependency}:** {Evidence, consequence, and affected identifiers.} -- **ASM-01 — {Assumption}:** {Evidence, consequence if wrong, and affected identifiers.} -- **RSK-01 — {Risk}:** {Evidence, consequence, mitigation or design response, and affected identifiers.} -- **UNR-01 — {Non-blocking uncertainty}:** {Evidence, consequence if wrong, affected decisions, and resolution condition or later user-agent step; explain why ticket decomposition remains safe.} - -## Traceability and readiness - -| Intent or acceptance identifier | Selected responsibility or contract | Verification seam or evidence | -| ------------------------------- | ------------------------------------ | ----------------------------------- | -| {REQ-01 or ACC-01} | {Design responsibility or contract.} | {Observable verification boundary.} | - -| Introduced design element | Originating intent, constraint, evidence, or accepted decision | -| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -| {Material responsibility, contract, data, integration, migration, operational, or verification element.} | {Exact identifier or linked authority.} | - -### Readiness statement - -{State concisely why later ticket creation can proceed without inventing observable behaviour or selecting a material solution, plus any non-blocking limitation. Do not recap the specification.} + diff --git a/skills/specify-feature/references/discovery.md b/skills/specify-feature/references/discovery.md new file mode 100644 index 0000000..b065af7 --- /dev/null +++ b/skills/specify-feature/references/discovery.md @@ -0,0 +1,33 @@ +# Feature discovery + +Use **goal-oriented use cases** for complete journeys and **Example Mapping** for rules, concrete examples and unresolved questions. Keep questioning within the feature boundary while exposing material details the user has not anticipated. + +## Establish the desired change + +Find the user's problem, beneficiary, intended outcome, current alternative and explicit exclusions. Test a foggy request with a concrete story about when the feature is used and what would count as success. Then follow the story into its rules and interactions. + +For “let users cancel bookings”, clarify what cancellation changes, who can cancel, when it is allowed and the outcome of refusal. Determine whether charges, notifications or freed capacity belong in scope. Do not infer a policy from the word “cancel”. + +## Follow every material path + +Use these lenses to construct the decision tree, rather than asking every prompt mechanically: + +- **Actors and entry:** who acts, through which supported interface, under what permissions and preconditions. Include external events and scheduled work. +- **Normal flow:** inputs, validation, defaults, rules, outputs, visibility, feedback and success. +- **State and time:** allowed and forbidden transitions, expiry, timezones, ordering, simultaneous actions and repeat execution. +- **Information:** definitions, ownership, sensitivity, lifecycle, retention and effects on existing data. +- **Adverse paths:** denial, missing or invalid input, cancellation, timeout, unavailable dependency, partial success, retries, recovery and effects that must never occur. +- **Experience and quality:** material interaction and content requirements, accessibility, operating conditions, measurable performance and compatibility. +- **Neighbours:** shared invariants, affected existing features, external contracts, migration and operations. + +Vary concrete examples at boundaries and search for counterexamples. If one condition changes the result, expose the rule that governs it. If combinations matter, use a decision table. If lifecycle matters, model states and transitions. Preserve general rules alongside examples so later agents can reason beyond the examples supplied. + +## Deepen consequential design + +Settle a design choice here when its alternatives change acceptance, shared contracts, state ownership, safeguards, migration, verification or the dependency graph. + +For an import, atomic failure versus partial success changes behaviour and later tickets. A private helper's name ordinarily does not. A concrete API contract or state table may be essential. A complete file inventory usually is not. Depth follows consequences rather than whether a detail is “technical”. + +## Test the handoff + +Walk the specification as a new planner. Can every trigger reach a defined result? Do examples agree with rules? Are all exits and forbidden effects covered? Can tickets share the same data and contracts without inventing policy? Are intentional exclusions and delegated coding choices clear? diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md deleted file mode 100644 index 512e0d6..0000000 --- a/skills/tdd/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: tdd -description: Teaches test-driven development through red-green-refactor with durable behavioural tests. Use when a usable suite can exercise changed behaviour through a credible seam. -metadata: - type: teaching -disable-model-invocation: true ---- - -# Test-Driven Development - -Teaches a caller to implement one observable behaviour at a time and retain a small suite that detects promised-behaviour defects without resisting structural change. - -## Prerequisites - -Apply TDD only when the work adds, changes, or repairs observable behaviour and an existing usable suite can exercise it through a credible seam. Otherwise surface the missing condition so the caller can use the strongest project-native feedback without claiming TDD. Create a suite or framework only when that infrastructure is part of the agreed work. - -## Process - -### 1. Fix the slice, seam, and oracle - -Use the caller's confirmed behaviour, applicable modular constraints, and current production and test evidence. Inspect only evidence that is missing or stale. Identify the focused command and run its baseline. Keep pre-existing failures visible; continue only when they cannot hide the next Red or Green signal. - -Select a **tracer bullet**: the smallest complete vertical slice that produces one requested observable outcome. Apply `$test-design` to choose its seam, oracle, test shape, and any conditional technique. Current output is characterization, not proof of correctness. - -For an existing partial implementation, demonstrate sensitivity against the pre-change revision, a safely disabled behaviour, or a controlled known-bad variant. When none is safe, retain an independently meaningful test as regression or characterization evidence without calling the work TDD. - -### 2. Red - -Write one focused behavioural test before its production change, following the selected test design. - -For a bug, reproduce the incorrect result and assert the independently established desired result. Structure the test so failure is reported against the promise: an unexpected exception that aborts before any oracle assertion is not Red unless the test explicitly establishes that successful completion is the promise. When count or order at a system boundary is promised, assert it directly rather than inferring it from final state. - -Run the focused test. Red exists only when an oracle fails for the intended missing or incorrect behaviour; a pass, syntax error, fixture failure, or environment error is invalid. Correct an in-scope test or environment defect and rerun, or surface the blocker in the caller's workflow. Preserve the exact Red command and failure. - -### 3. Green - -Add only enough production code for the current behaviour. Treat confirmed preconditions as inputs to this slice; do not invent validation, errors, fallbacks, or branches for their violation. Do not anticipate later cases, add hypothetical options, or refactor unrelated code. Run the focused test and relevant nearby tests. Fix production code while the independent oracle remains valid; never weaken the test merely to obtain Green. Preserve the exact Green command and result. - -### 4. Refactor while green - -Improve production naming, cohesion, duplication, ownership, and interfaces without adding behaviour. Keep behavioural tests unchanged through production refactors. When structural movement alone breaks a test, move its observation back to the promised outcome. Clarify test names or fixtures only without weakening the oracle or counterfactuals. Run the focused tests after each material step. - -If refactoring exposes a new material structural decision not resolved by the caller's modular constraints, pause the cycle until the caller resolves it. - -### 5. Rationalise the retained suite - -After production refactoring, reapply `$test-design` to the affected suite while it remains Green. - -### 6. Complete the cycles - -Repeat Red, Green, Refactor, and rationalisation for each remaining confirmed behaviour. Run the complete relevant suite. - -Keep the delivered behaviours, retained tests and their unique protection, exact Red and Green evidence, refactors, commands and results, unresolved baseline failures, fidelity limits, and other missing evidence current in the caller's workflow. diff --git a/skills/tdd/agents/openai.yaml b/skills/tdd/agents/openai.yaml deleted file mode 100644 index d3df8d3..0000000 --- a/skills/tdd/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Test-Driven Development' - short_description: 'Build durable behaviour through red-green-refactor' -policy: - allow_implicit_invocation: false diff --git a/skills/test-design/SKILL.md b/skills/test-design/SKILL.md index e4ad25c..3020f0b 100644 --- a/skills/test-design/SKILL.md +++ b/skills/test-design/SKILL.md @@ -1,59 +1,27 @@ --- name: test-design -description: Teaches durable behavioural test design through stable seams, independent oracles, determinism, and counterfactual challenge. Use when writing, reviewing, or rationalising tests. -metadata: - type: teaching -disable-model-invocation: true +description: Design minimal behavioural tests when application behaviour changes or testing work is explicitly requested. --- -# Test Design +# Test design -Teaches a caller to retain tests that detect promised-behaviour defects without resisting hidden structural change. +Protect **behavioural promises** with the fewest meaningful tests. Exercise the supported entry used by a person or system. Tests must survive internal refactors that preserve those promises. -## Process +## Inputs -### 1. Fix the behavioural basis +Take the behaviour to test from confirmed requirements, acceptance criteria or documented contracts. Derive expected results independently of the implementation. Resolve missing intended behaviour before its test. Current behaviour is authority only for explicitly requested characterisation work. -Use the caller's confirmed behaviour, applicable contracts, and current production and test evidence. Inspect only evidence that is missing or stale. Treat representation as a valid oracle only when that representation is itself a published contract. +## Method -### 2. Select a durable seam +1. **Decide eligibility.** Without an existing testing framework, stop silently. Add no tests, framework recommendation or testing-gap report. Otherwise, new or corrected observable behaviour requires **TDD**. Cosmetic edits, maintenance and behaviour-preserving refactors acquire no new coverage unless testing work is explicitly requested. Judge the actual promise, not the task label. Repair existing brittle tests while preserving useful coverage. The caller still owns existing checks and direct verification. +2. **Choose the behavioural seam.** Drive the actual UI, HTTP route, CLI command, library product API, scheduled job or queue-consumer entry through real internal collaborators. An exported private helper is not a supported entry. Consult [$modular-design](../modular-design/SKILL.md) when interface ownership needs judgement. Read [test techniques](references/test-techniques.md) before writing or repairing tests and [entry examples](references/entry-examples.md) for CLI, library or automated work. +3. **Select the promises.** Map requested promises to existing coverage. Extend or add tests only for missing protection, using representative inputs and material outcomes. Keep several cohesive assertions when they establish one promise. Trace invalid inputs through supported runtime paths. A mock-created bad value does not prove a defence necessary or redundant. Leave production deletion decisions to the caller. +4. **Build the arrangement.** Follow repository conventions and create missing harnesses, model factories and fixtures. Missing scaffolding is work to complete, not a skip condition. Keep application-owned logic and disposable persistence real. Read [test doubles](references/test-doubles.md) for external services, time or randomness. Use **Arrange–Act–Assert**, independent expected results and observable completion. Isolate state and release resources after every test. +5. **Run red–green–refactor.** For each behaviour change, write or adapt one test and observe failure for the intended missing behaviour before implementation. Setup, import and syntax failures are not red. Implement only enough to satisfy the promise, run green, then refactor while green. Complete the cycle before the next promise. A shared rule may satisfy further cases immediately. Retain their useful protection without breaking correct code to manufacture red. Test-only repairs and characterisation work require no artificial red. +6. **Challenge and verify.** Name the promise each retained test protects and an internal refactor it tolerates. Remove redundant or implementation-coupled tests only after preserving useful protection. Never weaken an expectation to accommodate incorrect behaviour. Run affected tests after the final edits. The caller owns broader checks and independent review. -Use the narrowest seam that is: +## Finish -- **Observable:** exposes a supported result, state, error, effect, persistence, navigation, or user-perceivable outcome. -- **Stable:** hides algorithms, collaborator graphs, storage layouts, rendering wrappers, generated selectors, and other replaceable decisions. -- **Predictive:** exercises the behaviour and technology whose production failure matters. +Return concise evidence of the tested entries, protected promises, independent expectations, observed red and green where applicable, and affected test results. Report an actual execution blocker precisely. Without a framework, return no testing message. During read-only cleanup or review, apply these rules to findings without editing or starting an implementation cycle. -Add a broader companion test only when the narrower seam cannot retain a material integration risk. Test a pure rule through its public function, a database guarantee against the real engine when its semantics matter, and an end-user interaction through the rendered application when wiring or accessibility is part of the promise. - -Prefer supported operations and observable outcomes over private methods, helper delegation, ORM calls, CSS classes, wrapper tags, DOM depth, stack shape, or broad incidental snapshots. For a defect, reproduce the wrong result and assert a requirement-derived correction rather than treating the existing failure as the expectation. - -When a slow, unavailable, destructive, non-deterministic, externally mutating, or otherwise uncontrollable boundary needs substitution or observation, load [Test Doubles](references/TEST-DOUBLES.md). Keep internal collaborators real and do not introduce a production abstraction solely to enable mocking. - -### 3. Build an independent oracle - -Prefer, in order: - -1. a confirmed requirement, accepted worked example, published protocol, or domain decision; -2. a law, invariant, or contract independent of the production algorithm; -3. a trusted external reference or separately implemented model; or -4. accepted prior behaviour when preservation is the requirement. - -Encode the expectation as an independently reasoned literal or predicate. Do not call the production helper, copy its algorithm, approve newly captured output, or assert only that execution completed unless completion is the entire promise. When no credible oracle exists, surface the missing behavioural decision in the caller's workflow. - -When examples cannot economically cover a large input or state space, or a direct expected output is unavailable but an independent relation, model, or comparator exists, load [Generative Testing](references/GENERATIVE-TESTING.md). Use only the technique whose trigger and oracle hold. - -### 4. Make the test deterministic and complete - -Arrange local explicit state, perform one meaningful action, assert the complete promised outcome, then release acquired resources. Add a negative or unchanged-state assertion only when the requirement makes it material and the action has a real causal path to the observed value. One behaviour may need several cohesive assertions; split multiple independent actions or rules. - -Control time and randomness through a deterministic source at the system boundary. Use fixed instants and seeds and preserve a minimised failing counterexample. Give each test isolated data and restore process state, files, transactions, services, timers, and environment values it changes. Avoid sleeps, execution-order dependencies, live external services, and shared mutable fixtures. - -### 5. Challenge and rationalise - -Apply both counterfactuals before retaining a test: - -- If promised behaviour broke, would this test fail? -- If only hidden structure changed, would this test remain unchanged and pass? - -Map every affected test to unique protection after refactoring. Keep a focused example when it specifies a distinct rule or gives a clearer failure. Otherwise remove duplicates or consolidate cases only when the resulting oracle and failure diagnosis remain clear. Fewer tests are better only when no unique defect detection is lost. +**Done only when** requested promises have meaningful protection through supported entries, newly implemented behaviour had an intended red before green, retained tests tolerate internal refactoring, and affected tests pass. Stop within the requested behaviour or testing scope. diff --git a/skills/test-design/agents/openai.yaml b/skills/test-design/agents/openai.yaml index bd620c2..ffd79ac 100644 --- a/skills/test-design/agents/openai.yaml +++ b/skills/test-design/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Test Design' - short_description: 'Design durable behavioural tests' -policy: - allow_implicit_invocation: false + short_description: 'Protect behavioural promises with minimal tests' diff --git a/skills/test-design/references/GENERATIVE-TESTING.md b/skills/test-design/references/GENERATIVE-TESTING.md deleted file mode 100644 index 63e43a4..0000000 --- a/skills/test-design/references/GENERATIVE-TESTING.md +++ /dev/null @@ -1,32 +0,0 @@ -# Generative Testing - -Use an example test by default. Select one of these techniques only when its trigger applies and its oracle is independently justified. - -| Technique | Trigger | Oracle and limitation | -| ------------------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Property-based** | Stable invariants over many values; parsers, serializers, algebra, collections, boundary-rich pure logic | Assert an independent invariant. Biased generators and tautological properties can pass indefinitely. | -| **Model-based** | Stateful workflows or protocols where sequences and invalid transitions matter | Compare with a smaller independent state model. A model copied from production repeats its defects and can suffer state explosion. | -| **Metamorphic** | Direct expected outputs are unavailable but relationships between executions are known | Assert relations such as round-trip, permutation invariance, monotonicity, or scaling. A relation detects inconsistency, not necessarily the uniquely correct result. | -| **Differential** | Two genuinely comparable implementations, versions, backends, or conforming tools can receive the same inputs | Compare normalized outcomes. Agreement may be jointly wrong; shared code or assumptions weaken independence. | - -## Apply the selected technique - -1. State the rule and its authority before writing the generator or model. -2. Constrain generated data to valid and deliberately invalid domains that exercise the promised behaviour. -3. Reject vacuous properties, unreachable model states, shared oracle logic, and normalization that erases material differences. -4. Run with a recorded seed. Minimize a failure and retain the smallest counterexample as a focused regression test. -5. Report the sampled scope and the oracle's limitation; a passing generated run is not proof over the full space. - -```typescript -// Tautological: repeats the implementation's sorting comparison. -property(array(integer()), (values) => - expect(sort(values)).toEqual(values.toSorted(productionComparator)), -); - -// Independent metamorphic relation: permutation cannot change the multiset. -property(array(integer()), (values) => - expect(frequencies(sort(values))).toEqual(frequencies(values)), -); -``` - -For stateful behaviour, keep the model smaller than production and express only authoritative states and transitions. For differential testing, first identify allowed variation and normalize only that variation. Preserve every meaningful discrepancy until it is explained as a candidate defect, an oracle defect, or permitted divergence. diff --git a/skills/test-design/references/TEST-DOUBLES.md b/skills/test-design/references/TEST-DOUBLES.md deleted file mode 100644 index a18429a..0000000 --- a/skills/test-design/references/TEST-DOUBLES.md +++ /dev/null @@ -1,63 +0,0 @@ -# Test Doubles - -Keep collaborators inside the system real. Substitute a boundary only when the real dependency is slow, unavailable, destructive, non-deterministic, externally mutating, or otherwise uncontrollable in this test. - -## Choose the least powerful double - -| Double | Supply | Verify | -| ------ | -------------------------------------------------- | -------------------------------------------- | -| Dummy | An unused required value | Nothing | -| Stub | A controlled indirect input | The public outcome | -| Fake | A small working boundary implementation | The public outcome or recorded public effect | -| Spy | A record of an otherwise invisible boundary effect | Only promised boundary facts | -| Mock | An expected external interaction protocol | Only contractually material calls | - -Prefer state verification. Interaction verification is warranted when the interaction is the promise: for example, one idempotency-keyed payment request or publishing only after a durable write. - -```typescript -// Brittle: replaces internal policy and specifies its call graph. -expect(pricing.lookup).toHaveBeenCalledTimes(1); -expect(discounts.apply).toHaveBeenCalledBefore(tax.apply); - -// Durable: real internal collaborators produce the supported result. -expect(await quoteOrder(order)).toEqual({ total: 108, currency: 'GBP' }); -``` - -At an uncontrollable external boundary, record only the promised effect: - -```typescript -const mailer = new RecordingMailer(); -await registerUser({ email: 'ada@example.com' }, { mailer }); - -expect(mailer.sent).toEqual([{ to: 'ada@example.com', template: 'welcome' }]); -``` - -Use a mock when interaction is the provider-facing contract: - -```typescript -expect(paymentGateway.charge).toHaveBeenCalledOnceWith({ - amount: 108, - currency: 'GBP', - idempotencyKey: order.id, -}); -``` - -When sequencing across system boundaries is promised, record those boundary events and assert their public order: - -```typescript -const events: string[] = []; -const payments = new RecordingGateway({ events, result: { paymentId: 'p-1' } }); -const orders = new RecordingOrders({ events, initial: pendingOrder }); - -await checkout(pendingOrder.id, { payments, orders }); - -expect(events).toEqual(['charge-succeeded', 'order-saved']); -``` - -This protects a payment-before-persistence promise. Ordering between pricing helpers, mappers, or other internal collaborators remains hidden structure. - -Do not assert logging, helper calls, object construction, or internal order unless those facts are externally promised. - -## Preserve boundary fidelity - -Derive double responses from the external contract, not copied client logic. Keep the double smaller than the real boundary. Prefer a real database or filesystem in an isolated disposable environment when its semantics matter. When feasible, use caller-selected contract evidence against the real boundary to check that a fake, stub, or recorded request remains compatible; otherwise report the untested fidelity. diff --git a/skills/test-design/references/entry-examples.md b/skills/test-design/references/entry-examples.md new file mode 100644 index 0000000..e4022c6 --- /dev/null +++ b/skills/test-design/references/entry-examples.md @@ -0,0 +1,88 @@ +# CLI, library and automated entries + +Read when the behavioural promise belongs to a command, library or automated process. These illustrative fixtures use real internal components and isolated persistence. The caller of the entry can be a person, another programme, a scheduler or a message broker. + +## CLI commands + +Invoke the production command with arguments, input and environment its user can supply. Observe stdout, stderr, exit status and promised files or effects. Calling the parser alone misses command wiring and execution. + +The illustrated `notes create` command must write a note that `notes show` can retrieve. + +```typescript +// Bad. Checks argument parsing without running the command. +expect(parseArgs(['create', '--title', 'Release'])).toEqual({ + command: 'create', + title: 'Release', +}); + +// Good. The fixture launches the real executable in an isolated data directory. +test('a created note is retrievable', async () => { + const cli = await testCli(); + const created = await cli.run(['create', '--title', 'Release', '--json']); + expect(created.exitCode).toBe(0); + const { id } = JSON.parse(created.stdout); + const shown = await cli.run(['show', id, '--json']); + expect(shown.exitCode).toBe(0); + expect(JSON.parse(shown.stdout)).toMatchObject({ id, title: 'Release' }); +}); +``` + +Keep exact stderr or formatting assertions when the command contract promises them. Otherwise assert the meaningful diagnostic or parsed result. The fixture must preserve command exit codes and clean up even after failure. + +## Scheduled jobs and queue consumers + +Invoke the entry registered with the scheduler or consumer with its supported context or message. Keep parsing and dispatch when they are part of the promise. Calling an internal worker alone cannot establish broker-message validation or scheduler registration. + +This reconciliation job promises to record a provider's settled amount for a pending payment. The factory creates a real stored payment. The provider fixture supplies the external HTTP response. The entry and internal reconciliation path remain real. + +```typescript +// Bad. Replaces the application behaviour and pins its internal call. +payments.update = vi.fn(); +await reconcileOne({ id: 'pay-1' }, payments); +expect(payments.update).toHaveBeenCalled(); + +// Good. Run the same entry the scheduler invokes and observe its result. +test('reconciliation records the settled payment amount', async () => { + const { jobs, payments, provider } = await testApp(); + const pending = await payments.factory.create({ + state: 'pending', + providerId: 'settlement-1', + }); + provider.respondWith( + settlementFixture({ + id: 'settlement-1', + amount: 1500, + currency: 'GBP', + }), + ); + + await jobs.reconcilePayments.run(); + + expect(await payments.read(pending.id)).toMatchObject({ + state: 'reconciled', + settledAmount: 1500, + currency: 'GBP', + }); +}); +``` + +Use a supported read interface where available. If the automated process's contract is the durable record or exported file itself, inspect that effect directly. Assert contractual values rather than incidental schema, SQL or intermediate flags. Await the job or its documented completion signal. + +For a promised idempotent consumer, deliver the same supported message twice and observe one resulting effect. For a promised transition rule, attempt allowed and forbidden transitions through the entry. Do not set private flags merely to hit a branch. These cases belong only when their behavioural promises are in scope. + +## Library products + +For a library, its consumers are users. Call the supported package API directly. A unit test is sufficient when that entry exercises the promised behaviour. Exporting an application helper for convenience does not turn it into a library product. + +Suppose the invoice library promises to parse this document into a public result. + +```typescript +// Bad. Pins a replaceable tokenisation step. +expect(tokeniseInvoice('INV-7,125')).toEqual(['INV-7', '125']); + +// Good. The supported package entry exposes the complete promised result. +import { parseInvoice } from 'invoice-library'; +expect(parseInvoice('INV-7,125')).toEqual({ id: 'INV-7', total: 125 }); +``` + +Choose the seam by its supported contract, not by the labels unit, integration or end-to-end. Keep the least machinery that exercises the complete promise. diff --git a/skills/test-design/references/test-doubles.md b/skills/test-design/references/test-doubles.md new file mode 100644 index 0000000..a3eab01 --- /dev/null +++ b/skills/test-design/references/test-doubles.md @@ -0,0 +1,74 @@ +# Test arrangements and doubles + +Read when tests need external responses, effect recording, controlled time or randomness. Use real application-owned collaborators, database access and disposable persistence. A repository mock cannot detect a broken query or transaction. + +## Factories and fixtures + +Follow the repository's arrangement conventions. When it uses model factories, create a missing factory rather than scattering raw inserts through tests. Give factories valid defaults and explicit overrides for the values relevant to the promise. Keep each instance independent. Use plain fixture data where that is the established convention. Keep the action under test out of the factory. + +```typescript +// Bad in a repository with model factories. Repeats incidental setup. +await db.insert('payments', { + id: 'pay-1', + accountId: 'account-1', + state: 'pending', + amount: 1500, + currency: 'GBP', + createdAt: '2026-01-01', +}); + +// Good. The factory owns valid construction and persistence. +const pending = await paymentFactory.create({ amount: 1500, currency: 'GBP' }); +``` + +Build missing launch, authentication, data-isolation and cleanup facilities within the existing framework. Reuse available infrastructure before adding machinery. Production API changes need behavioural or ownership justification beyond making mocks convenient. + +## Double only the external boundary + +Use the installed framework's interception or injection facility at the production boundary. Preserve the internal path that creates the request and handles the response. Replace external API calls with fixtures, not live provider calls. + +| Need | Suitable double | Observe | +| ------------------------------------- | -------------------------- | ------------------------------ | +| Supply a provider response or failure | Stub or response fixture | Application outcome | +| Record an externally promised effect | Spy or recording fake | Contractual payload and effect | +| Check an external protocol | Mock | Required protocol facts | +| Control time or randomness | Controlled clock or source | Application outcome | + +Derive response fixtures from the provider's documented contract or an approved representative response. Include required shape and status. A type cast does not establish fidelity. Keep the fixture smaller than a simulated provider application. Report material unverified fidelity when it limits the result. + +```typescript +// Bad. Bypasses the provider adapter and application pricing. +pricing.total = vi.fn().mockReturnValue(1500); +await checkoutInternal(cart); +expect(pricing.total).toHaveBeenCalled(); + +// Good. The seeded cart is £15. Only the external provider is controlled. +provider.respondWith(paymentAcceptedFixture({ id: 'charge-1' })); +const response = await client.request('/checkout', { + method: 'POST', + body: JSON.stringify({ cartId: 'cart-1' }), +}); +expect(response.status).toBe(201); +expect(await response.json()).toMatchObject({ state: 'confirmed' }); +expect(provider.requests).toEqual([ + { amount: 1500, currency: 'GBP', idempotencyKey: 'cart-1' }, +]); +``` + +The outgoing payload is itself promised in this example. Assert counts or order only when the external protocol requires them. Internal helper order is replaceable structure. For an external refusal, provide its contract-faithful response and check the promised refusal and unchanged payment state. + +## Control nondeterminism + +Use explicit relevant factory values, controlled boundary clocks and seeded random sources. Keep identifiers or incidental timestamps out of exact equality unless promised. Give tests independent database state, temporary directories and ports. Restore patched globals and stop processes the fixture started in guaranteed teardown. + +```typescript +// Bad. Sleeps on real time and depends on machine load. +await sleep(1000); +expect(await client.invoice()).toMatchObject({ state: 'expired' }); + +// Good. The contract expires an invoice at this instant. +clock.set('2026-01-01T12:00:00Z'); +expect(await client.invoice()).toMatchObject({ state: 'expired' }); +``` + +If timer callbacks drive the transition, advance the controlled timers and await their completion before observing it. A frozen wall clock alone does not run queued work. For concurrency promises, coordinate the competing actions through supported entries and observable barriers rather than relying on arbitrary sleeps. diff --git a/skills/test-design/references/test-techniques.md b/skills/test-design/references/test-techniques.md new file mode 100644 index 0000000..e40d4e4 --- /dev/null +++ b/skills/test-design/references/test-techniques.md @@ -0,0 +1,167 @@ +# Test techniques + +Read before writing or repairing behavioural tests. These bad/good pairs are illustrative TypeScript. Adapt syntax and fixture names to the repository. Fixtures boot the real application with isolated state and own cleanup. The contracts stated beside each example supply its expectations. + +## Arrange–Act–Assert through the real entry + +Arrange relevant starting state, act through the supported entry, then assert the promised outcome. Keep the action under test visible in the test body. A read used to observe a write belongs to Assert. Several related assertions can establish one promise. + +For an HTTP profile service, saving a name must make it retrievable. Testing internal delegation cannot establish routing or persistence. + +```typescript +// Bad. The mock supplies the result and the assertion pins delegation. +const profiles = { save: vi.fn().mockResolvedValue({ name: 'Ada' }) }; +await updateProfileHandler({ name: 'Ada' }, profiles); +expect(profiles.save).toHaveBeenCalledWith({ name: 'Ada' }); + +// Good. The real write and read establish the promise. +test('a saved profile name is retrievable', async () => { + // Arrange. + const { app, users } = await testApp(); + const ada = await users.create(); + const client = app.asUser(ada); + + // Act. + const saved = await client.request('/profile', { + method: 'PATCH', + body: JSON.stringify({ name: 'Ada' }), + }); + + // Assert. + expect(saved.status).toBe(200); + const profile = await client.request('/profile'); + expect(await profile.json()).toMatchObject({ name: 'Ada' }); +}); +``` + +Choose the entry for the actual promise. An HTTP check does not establish that a UI button works. An isolated component is appropriate when the component itself is the delivered product. An internal component test does not replace the application journey that connects its collaborators. + +## Use an independent oracle + +An **oracle** supplies the expected result. Use a requirement, independently worked example or contractual predicate. A £10 item and a £5 item must yield a £15 cart. Observe the application, rather than a value assembled by the test. + +```typescript +// Bad. The expected value repeats production's calculation. +expect(total(items)).toBe(items.reduce((sum, item) => sum + item.price, 0)); + +// Good. The cart fixture contains the two known items. +const response = await client.request('/cart/cart-1'); +expect(await response.json()).toMatchObject({ total: 1500, currency: 'GBP' }); +``` + +Prefer precise values to `toBeTruthy()` or `not.toThrow()` when the promise supplies a result. Generated identifiers can use contractual predicates, such as a returned ID that retrieves the saved record. Exact values are useful when independently known, not because every output must be a literal. + +## Select representative cases + +Use **equivalence partitioning** to group inputs the contract treats alike. Use **boundary value analysis** at promised thresholds. These techniques select meaningful cases rather than multiplying fixtures or chasing coverage percentages. + +Suppose an API accepts integer seat counts from 1 to 5. Many interior values repeat the same protection. The adjacent valid and invalid values distinguish the two limits. + +```typescript +// Bad. Repeats the accepted interior without testing either limit. +test.each([2, 3, 4])('accepts %i seats', assertSeatsAccepted); + +// Good. Helpers send real requests and check contractual results. +test.each([ + [0, 422], + [1, 201], + [5, 201], + [6, 422], +])('%i seats returns %i', assertSeatResponse); +``` + +For combined business conditions, use a small **decision table** of meaningful outcomes. For stateful behaviour, use **state transition testing** through supported actions. Include material refusals, retries or concurrent actions only when their promises require them. Test the transition and resulting state, rather than assigning an internal state flag and asserting it back. + +## Test reachable invalid inputs + +Send invalid values through the boundary that can receive them. Trace validation, construction and mutation paths before deciding that an internal state is impossible. Static types alone do not validate HTTP bodies, environment values, stored data or provider responses. + +```typescript +// Bad. Fabricates a private state after the entry has validated it. +await expect(saveProfile({ name: null } as any)).rejects.toThrow(); + +// Good. The contract rejects an invalid network payload. +const response = await client.request('/profile', { + method: 'PATCH', + body: JSON.stringify({ name: null }), +}); +expect(response.status).toBe(422); +expect(await response.json()).toMatchObject({ error: 'name must be a string' }); +``` + +The bad test earns no protection if every runtime path enforces a string before that private call. A real unchecked path changes that conclusion. Propose a redundant-defence deletion only with evidence covering every supported path and later mutation. + +## Preserve meaningful absence checks + +A refusal must sometimes leave state unchanged. Establish that the action occurred and inspect the relevant result. A successful acknowledgement alone cannot establish that a forbidden effect did not happen. + +```typescript +// Bad. Reads the starting fixture without attempting the forbidden action. +expect(await owner.profile()).toMatchObject({ name: 'Ada' }); + +// Good. A stranger is forbidden to change Ada's name. +const refused = await stranger.renameProfile(ada.id, 'Changed'); +expect(refused.status).toBe(403); +expect(await owner.profile()).toMatchObject({ name: 'Ada' }); +``` + +Empty results, unchanged state and no-charge assertions can be the promise. Retain them when they can detect a real violation. Imagining a no-op implementation is a useful sensitivity check, not a blanket ban on absence assertions or a requirement to mutate production code. + +## Use stable UI actions and observable completion + +For UI behaviour, interact as a user does. Prefer accessible roles, labels and stable explicit contracts to CSS classes or DOM position. Use the framework's user-interaction helpers and retrying assertions. Await completion rather than guessing a sleep duration. + +```typescript +// Bad. Pins styling and assumes completion timing. +await page.locator('.save-button:nth-child(2)').click(); +await page.waitForTimeout(500); +expect(await page.locator('.toast').isVisible()).toBe(true); + +// Good. The promised saved name appears after Save completes. +await page.getByRole('textbox', { name: 'Display name' }).fill('Ada'); +await page.getByRole('button', { name: 'Save' }).click(); +await expect(page.getByRole('heading', { name: 'Ada' })).toBeVisible(); +``` + +A visibility assertion is meaningful when that element is the promised result. If persistence is promised, also reload or reopen through the supported UI. Restyling alone does not justify tests for pixel values. A change to keyboard access, focus or visibility can be a behavioural change even when implemented in CSS. + +## Assert the contract's scope + +Assert promised fields without pinning incidental output. Use exact equality when the entire output is contractual. Broad snapshots often couple tests to unrelated markup, diagnostics or metadata. + +```typescript +// Bad. Pins the whole response, including incidental metadata. +expect(await response.json()).toMatchSnapshot(); + +// Good. The promise concerns the saved name. +expect(await response.json()).toMatchObject({ name: 'Ada' }); +``` + +An explicitly requested visual regression or exact-format contract can warrant an approved snapshot. Review it against that authority. An automatic snapshot update does not establish correctness. + +## Replace rather than layer + +Repair or remove internal-delegation tests once their useful promises are protected through the supported entry. Preserve unique protection before deleting its old home. + +```typescript +// Before. Three tests pin the same implementation chain. +expect(handlerCallsService).toBe(true); +expect(serviceCallsRepository).toBe(true); +expect(repositoryCallsInsert).toBe(true); + +// After. The existing entry test observes the promised saved result. +expect(await client.profile()).toMatchObject({ name: 'Ada' }); +``` + +The after assertion must follow the actual save action shown in the first example. A renamed helper, merged service or changed query should leave the behavioural test green. A broken save must turn it red. + +## Keep TDD in vertical slices + +Plan the required promises, then write and run one test before its implementation. A list of cases is planning. Writing every test and then all production code is **horizontal slicing**. + +```text +Bad: write success, refusal and retry tests → implement all three → run tests +Good: success red → green → refactor → refusal red → green → refactor +``` + +If implementing a shared rule also satisfies a required retry case, retain that case when it adds useful protection. Do not remove correct logic to manufacture red. Behaviour-preserving refactors keep tests green. They do not initiate a new coverage campaign. diff --git a/skills/upgrade-dependencies/SKILL.md b/skills/upgrade-dependencies/SKILL.md index 6ac49f5..73a4c3e 100644 --- a/skills/upgrade-dependencies/SKILL.md +++ b/skills/upgrade-dependencies/SKILL.md @@ -1,45 +1,29 @@ --- name: upgrade-dependencies -description: Upgrades project packages and toolchain dependencies with compatibility checks and required migrations. Use when refreshing dependencies or upgrading their versions. -metadata: - type: performer -disable-model-invocation: true +description: Upgrade a codebase's dependencies when the user requests package, build, CI, or runtime version updates. --- -# Upgrade Dependencies +# Upgrade dependencies -Deliver compatible dependency upgrades, required migrations and verified local changes. +Deliver the newest compatible stable dependencies within scope through **incremental migration**. Preserve existing behaviour and unrelated work. -## Process +## Inputs -### 1. Establish scope +Take the codebase and limits from the request. By default, include major upgrades, development packages, package-manager pins, CI actions, and build or container dependencies. Change language/runtime versions only when requested. Prefer the newest compatible LTS, or actively supported stable release where LTS does not exist. Explicit limits take precedence. -Inspect the request, repository guidance and working tree; preserve unrelated changes. Resolve unclear scope through `$elicit-with-context`: patch/minor upgrades only or majors too; package dependencies only or the full project toolchain. Reuse explicit answers. Include development packages in package scope. Toolchain scope includes project runtime versions, package-manager pins, container images and CI actions. Machine-wide changes, publication and deployment need separate authorisation. +Use repository instructions, manifests, lockfiles, workspace ownership, runtime pins, and CI or deployment constraints. Resolve discoverable facts first. Invoke [$elicit-with-context](../elicit-with-context/SKILL.md) only for unresolved material decisions, such as expanding scope to unblock a target. Leave commits, publication, deployment, and machine-wide changes to separately authorised work. -### 2. Discover compatible targets +## Method -Identify the existing package managers, workspaces, manifests, lockfiles, runtime requirements and CI/deployment constraints. Record current versions and relevant baseline check failures. Run each manager's outdated command before dependency research, such as `composer outdated --locked --format=json`, `npm outdated --json`, `pnpm outdated` or `bun outdated`; check the installed CLI's help for supported options. For selected toolchain components without an outdated command, compare their pins with official release listings. +1. **Establish the baseline.** Identify dependency managers and actual tool/runtime versions. Inspect the working tree, run repository-required checks and available audits, and record existing failures. Inventory installed, allowed, and latest versions with native outdated commands. Include versioned CI and container references that these commands miss. Establish a way to restore only your changes before upgrading. +2. **Research before changing.** For each proposed batch, consult current official releases, support policies, compatibility metadata, changelogs, and upgrade guides across the entire installed-to-target interval. Map relevant breaking changes to code and configuration. Check peers, plugins, extensions, runtimes, platforms, affected workspaces, and known consuming projects. Record target versions, source links, required migrations, and compatibility evidence. Use solver diagnostics or dry runs where supported. Missing documentation is not proof of compatibility. Resolve missing evidence through official source or maintainer guidance, or block that target. +3. **Sequence verifiable batches.** Prioritise critical security fixes and blocking dependencies. For stale dependencies, bring the current major to its latest compatible patch/minor before major migration. Keep coupled dependencies together. Default to one major at a time, using each major's latest compatible patch. Take a shorter path only when official guidance explicitly supports it. Follow documented migration order and ecosystem pre-1.0 rules. Hold back unsupported, withdrawn, or incompatible targets with reasons. Preserve security policies and resolve conflicts rather than bypassing checks. +4. **Upgrade with native tools.** Use package-manager or framework upgrade commands and official codemods, with researched targets or bounded ranges. Verify command semantics against the installed CLI. Preserve dependency classification, range conventions, and workspace ownership. Let the manager generate lockfiles. Edit version declarations directly only where native tooling cannot express the change. Apply all required code and configuration migrations. Align affected project, container, and CI pins within scope, verifying release identifiers and preserving immutable pins. Read [upgrade techniques](references/upgrade-techniques.md) when targeting commands, coupled migrations, runtime constraints, or recovery need examples. +5. **Verify every batch before continuing.** Inspect actual resolved versions, manifest and lockfile diffs, unexpected transitive changes, and codemod output against the research and scope. Investigate newly exposed compatibility or migration requirements. Run repository-required checks and relevant behaviour tests. Add focused regression coverage where a migration exposes a material gap. Diagnose regressions and repair or restore the batch before dependent work continues. Preserve prior verified batches and unrelated edits. Continue independent work where safe, recording any blocked remainder. +6. **Prove the final state.** Reproduce installation from the final lockfiles with the configured tooling. Verify the resolved dependency graph and platform requirements, then run all required checks, available audits, and affected behaviour checks under the target runtime. Distinguish configured pins from versions actually tested. Rerun outdated discovery and review the complete diff. Account for every in-scope upgrade as applied or held back with evidence. Report unavailable checks and inherited failures separately from regressions. -Distinguish installed, allowed and latest versions. Check candidate metadata, peer dependencies, framework compatibility, runtime/extension requirements and platform support together before selecting targets. Use solver diagnostics or dry runs where available, such as Composer's `why-not`. Select a compatible stable set within scope; a major upgrade allowance does not require incompatible latest versions. Treat pre-1.0 compatibility according to the ecosystem's rules. Explain blockers rather than bypassing peer, platform or security constraints. +## Finish -### 3. Read the selected upgrade guidance +Return the upgraded codebase, old-to-new versions, required migrations and sources, validation commands and results, held-back items and reasons, and remaining limitations. Keep optional API changes and larger refactors separate. Local checks prove only the environments exercised. -Send a fresh research agent the selected versions, compatibility evidence, scope, relevant project constraints and known documentation links. Have it consult official upgrade guides and release notes across the installed-to-target interval, including required intermediate upgrades. Return source links, required migration steps, compatibility findings and separately labelled optional improvements; stop at research. Keep version selection and changes in the main thread. Reassess targets if research reveals a blocker. Report missing documentation rather than inventing migration requirements. - -### 4. Upgrade and migrate - -Use official package-manager or framework upgrade commands first. Use explicit target versions or bounded ranges when a general update would miss permitted upgrades or exceed scope. Preserve dependency classification, range conventions and workspace ownership. For example, Composer `update` resolves existing constraints while `require` changes them; npm `update` respects ranges while `install package@range` can change them. Verify options against the installed tool. Let the manager generate lockfiles. Edit manifests or toolchain configuration directly only where no suitable official command exists. - -Apply coupled upgrades and required migration steps in the documented order. Update affected code and configuration while preserving behaviour. When toolchain upgrades are included, align project, container and CI pins, preserve existing immutable pinning and verify release identifiers against their official source. Distinguish project pins from the runtime actually used locally or by a deployment provider. - -After resolution, inspect the actual manifest and lockfile diff. Check compatibility and official release/migration guidance for additional changed packages, including transitives, using their resolved versions rather than predicted targets. Reconcile unexpected changes with scope before proceeding. Repeat this reconciliation if the resolved set changes again. - -Apply changes required by the upgrade guides. Record optional newer APIs, simplifications and larger refactors for the final handoff; leave their adoption to the user. - -### 5. Verify and hand off - -Verify reproducible installation from the resulting lockfiles, dependency/platform validity and the project's required checks, including relevant tests, static analysis and builds. Use available security checks and report unresolved findings. Check migrated behaviour with existing coverage; add focused regression coverage where a material gap remains. Separate pre-existing failures from upgrade regressions and state unavailable checks honestly. - -Rerun outdated discovery and review the final diff for unintended source, generated-file or toolchain changes. Explain remaining upgrades instead of treating a nonempty outdated report as failure. Stop with verified local changes, or clearly identified blockers when completion is not possible. - -Return a concise account of old-to-new versions, required migrations, validation results, held-back upgrades with reasons and optional improvements tied to affected code and official guidance. Do not claim remote CI or deployment success from local checks. +**Done only when** every in-scope item is accounted for, the chosen set installs reproducibly, required migrations are complete, and compatibility, required checks, and affected behaviour pass. A blocker or unavailable verification leaves the affected work incomplete. Report the exact constraint, verified progress, and next action rather than claiming completion. diff --git a/skills/upgrade-dependencies/agents/openai.yaml b/skills/upgrade-dependencies/agents/openai.yaml index a848e9d..3f78f7b 100644 --- a/skills/upgrade-dependencies/agents/openai.yaml +++ b/skills/upgrade-dependencies/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Upgrade Dependencies' - short_description: 'Upgrade compatible dependencies and required migrations' -policy: - allow_implicit_invocation: false + short_description: 'Upgrade dependencies through verified migrations' diff --git a/skills/upgrade-dependencies/references/upgrade-techniques.md b/skills/upgrade-dependencies/references/upgrade-techniques.md new file mode 100644 index 0000000..42fe304 --- /dev/null +++ b/skills/upgrade-dependencies/references/upgrade-techniques.md @@ -0,0 +1,37 @@ +# Upgrade techniques + +These examples illustrate the method in [the skill](../SKILL.md). Versions and placeholders are illustrative. Consult current official documentation and the installed CLI before adapting commands. + +## Target the researched version + +A general update may stay inside existing ranges. For example, `npm update` cannot migrate `^2.0.0` to major 3. Use a targeted install after researching that migration. Preserve the original dependency group and range style. + +```sh +# Illustrative npm production dependency with a caret range. +npm install --save-prod 'library@^3.2.1' + +# Illustrative npm development dependency with an exact pin. +npm install --save-dev --save-exact 'build-tool@4.1.2' +``` + +[npm update](https://docs.npmjs.com/cli/commands/npm-update/) also has different manifest-saving defaults from [npm install](https://docs.npmjs.com/cli/commands/npm-install/). Check both the declaration and resolved version. Use the existing manager's equivalent command rather than introducing npm into another ecosystem. + +## Upgrade a coupled set + +Suppose a framework major needs a matching renderer, plugin, and type package. Research their compatibility together and treat the set plus its required migrations as one batch. A successful package installation does not prove the application's rendering still works. + +Use the framework's migration CLI where provided. [Angular's `ng update`](https://angular.dev/cli/update) and [update guide](https://angular.dev/update-guide) illustrate explicit major targets and automated migrations. Apply the guide to the project's actual starting version and usage. Review transformed files and exercise affected behaviour before advancing. + +## Respect runtime constraints + +Suppose a package's latest major needs Node 20 but the project must remain on Node 18. Confirm that requirement from release metadata. Select the newest supported package version compatible with the fixed runtime, or explain that no safe target exists. Report the blocked latest major and any runtime support limitation. A newer Node on the agent's machine does not establish Node 18 compatibility. + +For requested runtime upgrades, check the current [Node release policy](https://nodejs.org/en/about/previous-releases) or the language's own support policy. [PHP](https://www.php.net/supported-versions.php) uses active and security support periods rather than an LTS designation. Include extensions, native modules, base-image variants, and deployment support in the compatibility check. + +[Composer](https://getcomposer.org/doc/03-cli.md) provides `why-not` for blockers and `check-platform-reqs` for the real PHP and extensions. Its configured platform can differ from the machine running validation. + +## Restore a failed batch + +Before mutation, save the relevant files' current contents, including existing user edits. If a batch fails, use the failure to identify a missing migration or incompatibility. Repair it and rerun checks, or restore only that batch's changes and reinstall from its previous lockfile. Inspect the resulting files before another batch. + +For reproducibility, use the manager's locked-install mechanism. [npm ci](https://docs.npmjs.com/cli/commands/npm-ci/) checks manifest and lockfile agreement and replaces the installation. Run it in an appropriate environment for the project. Preserve previous successful batches and unrelated work when restoring. diff --git a/skills/write-prose/SKILL.md b/skills/write-prose/SKILL.md index 608ba61..715f0e9 100644 --- a/skills/write-prose/SKILL.md +++ b/skills/write-prose/SKILL.md @@ -1,47 +1,28 @@ --- name: write-prose -description: Writes and revises clear, engaging reader-facing prose in UK English with an adaptable professional, conversational voice. Use for articles, reports, documents, websites, social posts, and substantial prose within other human-facing outputs. -metadata: - type: teaching -disable-model-invocation: false +description: Write clear, succinct UK English when drafting or revising text for humans or agents. --- -# Write Prose +# Write prose -Teaches a caller to produce natural, reader-fit prose without weakening meaning, evidence or the caller's authority. +Write coherent, succinct text that its intended reader can understand on the first read. Preserve **meaning, evidence, and required wording**. -## Process +Use **plain language**, drawing on **ISO 24495-1** and **ASD-STE100 Simplified Technical English** as guides. -### 1. Fix the communication job +## Inputs -Use the caller's subject, facts, purpose, audience, medium, genre, constraints and required structure. Preserve exact quotations, proper names, technical terms and mandated wording. Use UK English for all other prose. +Take the writing brief or supplied draft from the request or caller handoff. Default to UK English. Match tone and register to the brief, audience, medium, and purpose. Follow explicit language, voice, and format requests. The caller owns factual investigation, substantive decisions, required structure, persistence, and workflow validation. -Load [Preferred Voice](references/PREFERRED-VOICE.md) and use it as the baseline. Adapt its energy and register to the audience, medium and genre. Follow a different voice only when the caller explicitly requests it; retain UK English. +## Method -Let the caller own the requested artefact and its factual, structural and procedural rules; apply this skill only to the prose. +1. **Orient the reader.** Lead with the useful point, stakes, or question. Include what the reader needs to understand or act. Use plain words and concrete actions, keeping specialist terms when their precision serves the audience. Ground unfamiliar concepts before relying on them. Read [voice guidance](references/preferred-voice.md) when tone or register is uncertain. +2. **Connect the reasoning.** Give each paragraph a clear job and order the material so each part earns the next. Connect claims to useful reasons, evidence, examples, trade-offs, or consequences. Put evidence near its claim. State uncertainty and its practical effect. Ground experience, quotations, agreement, and certainty in supplied authority. +3. **Make sentences unambiguous.** Use literal, complete sentences with one clear main point. Prefer active voice when the actor matters. Write instructions as direct commands, putting conditions before the actions they govern. Keep related conditions and consequences together. Give pronouns clear referents and keep terms consistent. Retain articles, verbs, and qualifications. Vary sentence length with the thought. Use lists for parallel items, numbers for sequences, and tables for comparisons. Read [writing techniques](references/writing-techniques.md) when explanation, emphasis, or structure needs a deliberate technique. +4. Use full stops and commas for authored prose. **Do not use em dashes, semicolons, or parentheses**, or substitute another dash for an em dash. Reserve colons for lists and examples. Preserve exact quotations, technical literals, and required formatting. Use sentence-case headings, sparse emphasis, and no decorative emojis by default. Follow the destination's quotation-mark style and explicit presentation requirements. +5. **Cut and check.** Read [natural prose review](references/natural-prose-review.md) before revising supplied text or reviewing a new draft. Repair unsupported claims, vague praise, stock framing, needless jargon, repetition, ambiguity, and over-compression. Cut words that do no useful work while preserving required behaviour, intensity, coverage, and completion gates. Read the whole piece again for fidelity, coherence, rhythm, and UK usage. End with the conclusion, implication, or next action it has earned. -### 2. Lead with substance +## Finish -Make the point, stakes or useful question clear early. Prefer concrete nouns, visible actions, exact details and strong accurate verbs. Explain necessary specialist language in place. +Return the requested text in its required form. Leave unresolved evidence gaps visible. -Make reasoning inspectable. Connect a claim to the most useful explanation, example, evidence, comparison, trade-off or consequence. Put evidence near the claim it supports. State uncertainty, limitations and competing considerations plainly, then explain their practical effect. - -Never invent experience, personality, quotations, evidence, agreement or certainty to create a voice. - -### 3. Shape the reading experience - -Give each paragraph or section a discernible job and order information so each part earns the next. Vary sentence shape, length, pace and punctuation when meaning or emphasis changes. Use active voice when agency matters and passive voice when the receiver properly leads. - -For prose that needs explanation, emphasis, engagement or information design, load [Writing Techniques](references/WRITING-TECHNIQUES.md). Select only techniques that perform a real job in this piece. Do not satisfy a style quota. - -### 4. Revise for natural prose - -For multi-paragraph prose, load [Natural Prose Review](references/NATURAL-PROSE-REVIEW.md). Review the whole piece before polishing sentences: - -1. Preserve the intended message, factual boundaries and useful structure. -2. Remove repetition, throat-clearing, empty intensifiers and implications already clear to the reader. -3. Replace vague or inflated wording with the most exact familiar language. -4. Break mechanical symmetry and monotonous cadence only where the reading experience needs it. -5. Read for rhythm, then correct grammar, punctuation and UK usage. - -End by closing the central loop with the conclusion, implication, recommendation or next action the piece has earned. Stop when another change would only make the prose different rather than clearer, more engaging or more faithful to the brief. +**Done only when** the whole piece matches the brief and supplied authority, preserves required wording and behaviour, and has been checked for coherence, ambiguity, and needless verbosity. Stop when further editing would merely make it different rather than clearer or more faithful. diff --git a/skills/write-prose/agents/openai.yaml b/skills/write-prose/agents/openai.yaml index cef082a..54afbc8 100644 --- a/skills/write-prose/agents/openai.yaml +++ b/skills/write-prose/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Write Prose' - short_description: 'Write engaging reader-facing UK prose' -policy: - allow_implicit_invocation: true + short_description: 'Write clear, succinct UK English for humans and agents' diff --git a/skills/write-prose/references/NATURAL-PROSE-REVIEW.md b/skills/write-prose/references/NATURAL-PROSE-REVIEW.md deleted file mode 100644 index 7958913..0000000 --- a/skills/write-prose/references/NATURAL-PROSE-REVIEW.md +++ /dev/null @@ -1,20 +0,0 @@ -# Natural Prose Review - -Inspect the piece for: - -- a generic opening that delays the actual subject; -- vague claims, missing examples or detail that cannot be inspected; -- repeated words, claims, sentence openings, transitions or conclusions; -- any em dash that could become a comma, full stop, colon, semicolon or parentheses, especially when more than one appears; -- paragraphs with conspicuously uniform length or function; -- repeated balanced clauses or triads; -- inflated vocabulary, needless intensifiers or a register more complex than the reader needs; -- over-explanation, restated implications and a conclusion that merely summarises the summary; -- headings, lists and transitions applied as a template rather than demanded by the material; -- uniform formality that obscures the writer's grounded point of view; -- invented or unchecked quotations, names, dates, numbers, citations or factual claims; and -- false familiarity, personal experience or collective language not supplied by the caller. - -Correct the underlying problem. Add specificity instead of decorative variation. Compress repetition instead of swapping synonyms. Change rhythm where thought and emphasis change. Preserve deliberate parallelism, repetition, technical vocabulary and genre conventions when they serve the piece. - -Default to no em dashes. Keep one only when a rare, strong interruption is clearer than quieter punctuation, and rewrite if more than one appears unless each is essential. Let contractions, sentence lengths and word strength follow meaning and register. diff --git a/skills/write-prose/references/PREFERRED-VOICE.md b/skills/write-prose/references/PREFERRED-VOICE.md deleted file mode 100644 index c470b9e..0000000 --- a/skills/write-prose/references/PREFERRED-VOICE.md +++ /dev/null @@ -1,17 +0,0 @@ -# Preferred Voice - -Use a **professional but conversational** voice. Sound like a capable person explaining something useful. Keep the voice direct and grounded rather than institutional. - -- State the subject or conclusion early, then explain why it holds. -- Prefer the sequence **claim, explanation, example or consequence** when it fits the material. -- Explain choices through relevant criteria and trade-offs rather than declaring one option universally best. -- Use plain language without removing necessary technical substance. Define unfamiliar terms where the reader meets them. -- Use first person for real choices, actions, experience and uncertainty supplied by the caller. Use ordinary contractions when the genre permits them. -- Keep paragraphs focused and transitions meaningful. Vary connectors rather than repeatedly announcing every example, contrast or conclusion. -- Prefer commas, full stops, colons or parentheses to em dashes. Most pieces should contain none; use one only in the rare case that a strong interruption is clearer than quieter punctuation. -- Admit a limitation directly and follow it with what it changes. -- Finish practically. Prefer a conclusion, implication, recommendation or next step to a broad flourish. - -Adjust the energy, intimacy and pace to the medium. Technical documentation should be calm and explicit. Reports should be evidence-led. Blog posts may be warmer, brisker and more personal. Social posts may compress the thought and sharpen the opening. Preserve the same clarity and grounded reasoning in each. - -Add warmth, humour or informality only when the subject and relationship support it. diff --git a/skills/write-prose/references/WRITING-TECHNIQUES.md b/skills/write-prose/references/WRITING-TECHNIQUES.md deleted file mode 100644 index 0b2d05a..0000000 --- a/skills/write-prose/references/WRITING-TECHNIQUES.md +++ /dev/null @@ -1,33 +0,0 @@ -# Writing Techniques - -Treat these as available tools. Choose a technique because of the job it performs, not because varied prose must contain it. - -## Orient the reader - -- **Direct opening:** State the point or problem when the reader needs immediate utility. Avoid generic scene-setting. -- **Narrative opening:** Begin with a real supplied moment or concrete case when experience will make an abstract subject tangible. Do not invent an anecdote. -- **Reader question:** Surface a genuine objection, invite a useful prediction or create a transition the answer fulfils. Avoid stock questions and empty requests for engagement. - -## Explain and persuade - -- **Example:** Make a general claim inspectable. Include the boundary that prevents the example from becoming a false universal rule. -- **Comparison:** Name the criterion, show the relevant alternatives and explain the consequence of the difference. -- **Analogy:** Map an unfamiliar idea to a familiar one, state where the mapping stops and retire it once direct explanation can carry the point. -- **Quotation:** Use exact words only when their wording or speaker matters. Attribute, contextualise and interpret them; paraphrase when only the information matters. -- **Direct address:** Use _you_ for a real reader action or relationship and _we_ only for genuine shared ground. Avoid synthetic intimacy or presumed agreement. - -## Control pace and emphasis - -- **Sentence contrast:** Give explanation room, then use a short sentence to land a real conclusion. Do not manufacture a short-long-short pattern. -- **Parallel phrasing or a triad:** Clarify genuinely comparable ideas or create a brief cadence. Do not pad a list to three or repeat the same pattern nearby. -- **Fragment, one-sentence paragraph or repetition:** Reserve it for an emphasis the surrounding prose has earned. -- **Humour or an aside:** Add local warmth or relief when it fits the writer's role and subject. Keep it subordinate to the message. - -## Expose structure - -- **Heading:** Name a useful stage or question in a longer piece. Avoid uniform template headings that could belong to any subject. -- **Bullets:** Use for related items readers may scan independently. -- **Numbers:** Use for sequence, rank or a fixed count. -- **Prose:** Keep connected reasoning in sentences and paragraphs when relationships and qualification matter more than item retrieval. - -Use punctuation to show relationships and pace. A full stop can isolate a conclusion, a colon can introduce an explanation and a semicolon can hold close independent clauses together. Choose the quietest mark that makes the relationship clear. diff --git a/skills/write-prose/references/natural-prose-review.md b/skills/write-prose/references/natural-prose-review.md new file mode 100644 index 0000000..4ab6cc2 --- /dev/null +++ b/skills/write-prose/references/natural-prose-review.md @@ -0,0 +1,393 @@ +# Natural prose review + +Use these patterns to find a problem in meaning or readability. Repair the cause instead of disguising it with synonyms, arbitrary variation, or invented detail. Apply them to the audience and genre in the brief. + +The paired examples are illustrative drafts. Bad examples deliberately contain the pattern under review. Each pair uses fixed illustrative facts established in its draft or explanation. + +For actual revisions, treat the caller's confirmed facts as authoritative. A supplied draft can contain unsupported claims. Keeping the same subject in a revision does not require preserving those claims. Facts, measurements, sources, and experiences must come from the task's evidence. When a detail is missing, remove the unsupported claim, qualify it, or leave the gap visible. + +## Claims and useful detail + +### Generic opening + +Start with the actual subject. Keep scene-setting only when a supplied situation helps the reader understand what follows. + +```markdown +// Bad +We are writing to inform you that your replacement charger will be dispatched on Thursday. + +// Good +Your replacement charger will be dispatched on Thursday. +``` + +### Vague praise or feeling + +Name the supplied behaviour. Remove praise that adds no supported behaviour or useful claim. + +```markdown +// Bad +Saving a filter and reusing it on the Tasks page delivers an effortless experience. + +// Good +You can save a filter and reuse it on the Tasks page. +``` + +### Decorative explanation + +Explain a consequence within the evidence. Remove a trailing phrase that claims more than the action establishes. A participial clause can remain when it expresses a real relationship, such as water cooling and forming ice. + +```markdown +// Bad +The service retries a failed request once, ensuring complete reliability. + +// Good +The service retries a failed request once. +``` + +### Unnamed authority + +Identify the available source, its finding, and the relevant criterion. Without a source, remove the attribution and assess whether the claim itself is supported. Here, appointment records are supplied, but no source supports the claim about experts. Never invent a citation to save a sentence. + +```markdown +// Bad +Experts agree that our new appointments reduce waiting. Our appointment records show that the average wait fell from eight minutes to five. + +// Good +Our appointment records show that the average wait fell from eight minutes to five. +``` + +### Unsupported strength + +Use a supplied measurement instead of an intensifier. Without evidence, remove the claimed improvement. Preserve adverbs that convey a real condition, such as temporary unavailability. + +```markdown +// Bad +The new appointments dramatically reduce waiting time. Our records show that the average wait fell from eight minutes to five. + +// Good +Our records show that the average wait fell from eight minutes to five. +``` + +### Excessive hedging + +Keep the uncertainty and, when known, what it means for the reader. Removing repeated hedges must not turn a forecast into a guarantee. + +```markdown +// Bad +Your delivery could potentially perhaps be delayed. + +// Good +Your delivery may be delayed. +``` + +### Empty conclusion + +Finish with an earned implication or useful action. Omit a closing paragraph when the piece is already complete. + +```markdown +// Bad +Delivery is expected on Monday. Reply if you would prefer a refund. We look forward to a brighter future together. + +// Good +Delivery is expected on Monday. Reply if you would prefer a refund. +``` + +Test what each sentence helps the reader understand or do. Relevant general advice remains useful even when it applies to several products. Product claims should describe the actual product. Wider explanations should state an applicable principle or relevant observation. + +## Wording and framing + +### Inflated wording + +Use plain words. Review words such as "leverage", "delve", "pivotal", "tapestry", and "underscore" for an unnecessary abstraction or flourish. A word's presence alone is not a defect. + +```markdown +// Bad +We endeavour to facilitate your utilisation of the service. + +// Good +We help you use the service. +``` + +### Padded identity or possession + +Use the verb that names the actual relationship. An alternative to "is" can remain when it adds meaning, such as a garage serving as a workshop. + +```markdown +// Bad +The venue boasts a garden and serves as a place for monthly meetings. + +// Good +The venue has a garden and hosts monthly meetings. +``` + +### Manufactured contrast + +State the supported change. Keep a contrast when readers need to distinguish real alternatives or correct a likely misunderstanding. + +```markdown +// Bad +You can now choose an evening appointment. This is not just a schedule change, but a new era of flexibility. + +// Good +You can now choose an evening appointment. +``` + +### False range + +Name the actual subjects. Keep ranges with meaningful endpoints, such as ages five to eleven. + +```markdown +// Bad +From trust to innovation, this guide covers it all through consent, record keeping, and complaints. + +// Good +The guide explains consent, record keeping, and complaints. +``` + +### Decorative jargon or metaphor + +Explain the action. Keep precise terms such as "vector" in a mathematical explanation and "test harness" in developer guidance. Explain a specialist term for an unfamiliar audience. + +```markdown +// Bad +Putting repairs before expansion provides a powerful vector for progress. + +// Good +The plan puts repairs before expansion. +``` + +### Mannered flourish + +Use literal wording by default. Preserve an image when it does useful explanatory or expressive work for the requested audience and genre. Use the techniques reference to make that choice. + +```markdown +// Bad +Friday's application deadline is a drumbeat that refuses to quieten. + +// Good +Applications close on Friday. +``` + +### Filler + +Remove introductions that add no qualification. Shorten padded phrases when nothing is lost. + +```markdown +// Bad +It is important to note that you must apply by Friday in order to attend. + +// Good +You must apply by Friday to attend. +``` + +### Automatic pleasantry or flattery + +Answer the question or acknowledge the particular point. Remove routine opening enthusiasm and generic closing offers. Keep a relevant apology, thanks, or offer when the relationship and task support it. + +```markdown +// Bad +Excellent question! You're completely right to ask. Applications close on Friday. I hope this helps! + +// Good +Applications close on Friday. +``` + +## Sentences and repetition + +### Synonym cycling + +Repeat the precise term when several names refer to the same thing. Keep different names when they identify different concepts. + +```markdown +// Bad +Save the filter. The preset is private. Rename the saved view later. + +// Good +Save the filter. The filter is private. You can rename it later. +``` + +### Forced triad or balance + +State the supported benefits, however many there are. Retain three items when there really are three, and parallel wording when it makes comparable ideas easier to follow. + +```markdown +// Bad +The library will open on Saturdays, bringing clarity, confidence, and empowerment to weekend visitors. + +// Good +The library will open on Saturdays, giving weekend visitors another day to use it. +``` + +### Dense sentence + +Keep qualifications beside the claims they affect. Split material that makes the reader backtrack. + +```markdown +// Bad +Although the form accepts late applications if places remain, which depends on cancellations, applicants must pay before attending and should wait for confirmation before booking travel. + +// Good +Late applications are accepted if cancellations leave places available. Wait for confirmation before booking travel. You must pay before attending. +``` + +### Unhelpful passive + +Prefer a known actor when the action matters. Passive wording is appropriate when the actor is unknown or irrelevant. Do not invent an actor. + +```markdown +// Bad +Each row is checked by the loader. + +// Good +The loader checks each row. +``` + +### Cryptic compression + +Restore articles, verbs, conditions, and meaningful relationships. Preserve exact command names and established abbreviations the audience understands. + +```markdown +// Bad +Any row has bad date → command exits 2, no records written. + +// Good +If any row contains an invalid date, the command exits with code 2 and writes no records. +``` + +### Mechanical rhythm or repetition + +Give each paragraph a distinct job. Merge repeated claims and vary sentence length with the explanation and emphasis. Useful repeated terminology and deliberate cadence can remain. + +```markdown +// Bad +The library opens on Saturdays. This means it is open at the weekend. + +Weekend visitors have another day to use the library. Saturday opening provides that extra day. + +// Good +The library opens on Saturdays, giving weekend visitors another day to use it. +``` + +A sentence can contain a condition and its consequences while still having one clear main point. Readability does not require making every sentence equally short. + +### Ambiguous reference + +Repeat the noun when a pronoun could identify more than one thing. Use the supplied relationship to resolve the reference. + +```markdown +// Bad +Copy the policy into the report and check that it contains the revision date. + +// Good +Copy the policy into the report. Check that the report contains the revision date. +``` + +### Condition or modifier in the wrong place + +Put a condition before the instruction it governs. Place "only" beside the restricted action or object. Preserve the supplied scope instead of choosing one for readability. Here, the preview is always available, but saving requires a valid mapping. + +```markdown +// Bad +Only preview and save the import if the mapping is valid. + +// Good +Preview the import. If the mapping is valid, save the import. +``` + +### Weakened agent instruction + +Cut padding while retaining the action, coverage, intensity, and stopping condition. Words such as "every", "before", and "until" can define required behaviour. + +```markdown +// Bad +Review the branches and summarise your understanding. + +// Good +Relentlessly traverse every material branch. Continue until each branch is resolved, explicitly delegated, or excluded by the agreed scope. Obtain confirmation of the complete synthesis before acting. +``` + +The good example preserves this illustrative task's contract. A shorter instruction that loses a gate is a change in behaviour. + +## Punctuation and presentation + +Apply the punctuation and presentation policy in [the skill](../SKILL.md). Restructure a crowded sentence before choosing a replacement mark. + +### Punctuation carrying too much structure + +Turn an aside into a separate sentence or integrate it with commas. Rewrite an explanatory colon as "because" or split the sentence. Preserve relationships and exact source wording. + +```markdown +// Bad +Your booking is confirmed (we received your payment); bring your letter: we need it to check you in. + +// Good +We received your payment, so your booking is confirmed. Bring your letter so we can check you in. +``` + +### Em dash or substitute dash + +Split or restructure the sentence. Keep a hyphen inside an established compound and a dash inside a required quotation or technical literal. + +```markdown +// Bad +Your appointment is confirmed — bring your letter. + +// Good +Your appointment is confirmed. Bring your letter. +``` + +### Repeated inline label + +Remove a label that repeats the sentence. Keep a useful lead-in when it adds information. Use connected prose when the bullet format adds no scanning value. + +```markdown +// Bad + +- **Delivery:** Delivery is expected on Monday. + +// Good +Delivery is expected on Monday. +``` + +### Decorative formatting + +Emphasise only what helps retrieval or a decision. Keep an emoji with a useful role in the requested voice or format. Follow the destination's quote style and required formatting. + +```markdown +// Bad + +## ✨ Your Upcoming Appointment + +Bring your **letter** to your **appointment** on **Monday**. + +// Good + +## Your appointment + +Bring your letter to your appointment on Monday. +``` + +### Template-shaped structure + +Give a short answer directly. Use headings for meaningful sections of longer work and lists for items readers need to scan independently. + +```markdown +// Bad + +## Overview + +Applications close on Friday. + +## Key takeaways + +- Apply by Friday. + +## Conclusion + +Remember to apply by Friday. + +// Good +Applications close on Friday. +``` + +Check the whole piece again after local edits. Preserve the brief, necessary reasoning, uncertainty, and required wording. A cleaner sentence must not conceal a lost fact or qualification. diff --git a/skills/write-prose/references/preferred-voice.md b/skills/write-prose/references/preferred-voice.md new file mode 100644 index 0000000..a25fa97 --- /dev/null +++ b/skills/write-prose/references/preferred-voice.md @@ -0,0 +1,134 @@ +# Voice and register + +Match the voice to the reader, relationship, medium, and purpose. + +The paired examples are illustrative. Use only facts established for the actual task. Never create a number, anecdote, source, or audience preference to make writing sound grounded. + +## Direct and grounded + +Lead with the useful point, then explain why it holds. The sequence of claim, explanation, and example or consequence often works, but it is not a compulsory paragraph template. + +### Lead with the consequence + +Give the reader the practical change first. Include the reason afterwards when supplied. + +```markdown +// Bad +We wish to inform you of an alteration to the delivery schedule, with Monday now being the expected arrival date. + +// Good +Your delivery is now expected on Monday. +``` + +### Explain a choice through criteria + +Use relevant criteria and trade-offs instead of declaring an option universally best. + +```markdown +// Bad +Option A supports offline access. Option B costs less but requires a connection. Clearly, option A is the superior choice. + +// Good +Choose option A if you need offline access. Option B costs less but requires a connection. +``` + +### Connect a claim to its consequence + +Show why a supported change matters to the reader. + +```markdown +// Bad +The library will open on Saturdays, offering several important benefits for weekend visitors. + +// Good +The library will open on Saturdays. That gives weekend visitors another day to use it. +``` + +## Warmth without invented intimacy + +Use ordinary contractions when the genre permits them. First person can express a real choice, action, experience, or uncertainty supplied by the caller. Use "you" for a reader's real action and "we" for established shared ground. + +### Avoid presumed reactions + +Explain an available choice without inventing how the reader will feel about it. + +```markdown +// Bad +You will undoubtedly love being able to choose a morning or evening appointment. + +// Good +You can choose a morning or evening appointment. +``` + +### Acknowledge the actual situation + +A relevant apology can be warm without claiming shared experience. Use it when the writer's role supports it. + +```markdown +// Bad +Your delivery is late. We all know how frustrating that can be. + +// Good +I'm sorry your delivery is late. +``` + +### Ground first person in evidence + +Invented personal experience cannot replace evidence. Retain real first-person experience when the caller supplied it. Here, test results are available, but the personal claim is not. + +```markdown +// Bad +I have always found this method reliable. The supplied tests passed, although they do not cover interrupted connections. + +// Good +The supplied tests passed, but they do not cover interrupted connections. +``` + +### Make an offer useful + +Keep thanks, apologies, and offers tied to the actual exchange. A generic closing offer adds little when the requested answer is complete. + +```markdown +// Bad +Let me know if there is anything else I can help with. You can request a refund by replying. + +// Good +Reply if you would prefer a refund. +``` + +## Match the medium + +- In technical documentation, state behaviour and conditions directly. A developer familiar with queues usually needs the ordering rule, not a waiting-line analogy. +- In agent instructions and skills, use direct commands. Preserve the required intensity, scope, conditions, and stopping rules when simplifying the wording. +- In reports, put supplied evidence near the claim and qualify what can be inferred from it. +- In customer correspondence, give the practical consequence, relevant reason, and available action. Keep the tone considerate without inventing reassurance or guarantees. +- In articles and blog posts, a supplied scene can give an unfamiliar idea context. Retain a grounded point of view and enough explanation for the intended reader. +- In social posts and spoken scripts, pace and emphasis may be brisker. Keep the conditions that make the message accurate and the complete sentences that make it understandable. + +Add warmth, humour, or informality when the subject and relationship support it. Follow the punctuation and presentation policy in [the skill](../SKILL.md). + +## Honest limits and endings + +### State uncertainty and its effect + +Keep a forecast useful without promising more than the evidence permits. In this example, Monday is an expected date, not a guarantee. + +```markdown +// Bad +Your delivery is expected on Monday, so you can be certain it will arrive then. + +// Good +Your delivery is expected on Monday, but the date is not guaranteed. +``` + +### Finish practically + +End with an earned conclusion, implication, recommendation, or next action. A short explanation may need no separate ending. + +```markdown +// Bad +Submit the form by Friday. Together, we can look forward to exciting possibilities ahead. + +// Good +Submit the form by Friday. +``` diff --git a/skills/write-prose/references/writing-techniques.md b/skills/write-prose/references/writing-techniques.md new file mode 100644 index 0000000..349b46a --- /dev/null +++ b/skills/write-prose/references/writing-techniques.md @@ -0,0 +1,255 @@ +# Writing techniques + +Default to literal, complete sentences. Choose a technique when it performs a clear job for the intended reader and genre. Stop using it once direct explanation can carry the point. Follow the punctuation and presentation policy in [the skill](../SKILL.md). + +The paired examples use illustrative facts. Bad marks a weaker choice for the stated reader and purpose. In an actual task, use supplied facts and preserve any qualification that makes them accurate. + +## Orient the reader + +### Direct opening + +State the point when the reader needs immediate utility. Give the needed document and next step from supplied facts. + +```markdown +// Bad +As part of our ongoing commitment to a thorough application process, we need you to provide proof of address. + +// Good +Your application needs proof of address. +``` + +### Narrative opening + +Use a supplied event when it makes a problem tangible. Do not invent a scene or delay an urgent instruction for atmosphere. + +```markdown +// Bad +There are important considerations around the timing of our sessions. At Tuesday's session, three visitors arrived after the doors had closed. + +// Good +At Tuesday's session, three visitors arrived after the doors had closed. +``` + +### Reader question + +Introduce a real concern the following text answers. Remove stock engagement questions. + +```markdown +// Bad +Ready to transform your upload experience? An interrupted upload resumes after the connection returns. + +// Good +What happens if the connection drops during an upload? The upload resumes after the connection returns. +``` + +## Explain and persuade + +### Example + +Make an abstract claim inspectable through a supported case. State any boundary the reader needs. A single example does not establish every possible case. + +```markdown +// Bad +Filters provide powerful task organisation. You can filter for overdue tasks assigned to you. + +// Good +A filter can show overdue tasks assigned to you. +``` + +### Comparison + +Name the criterion and consequence. Use the supplied differences to help the reader assess options. + +```markdown +// Bad +Flying is clearly the best way to travel. The flight is quicker, but it needs an airport transfer. The train takes longer and arrives in the town centre. + +// Good +The train takes longer, but it arrives in the town centre. The flight is quicker, but you also need an airport transfer. +``` + +### Analogy for an unfamiliar idea + +Use an analogy only when the intended reader needs help. Follow it with the real mechanism and any important limit. Here, a less technical reader is unfamiliar with first-in, first-out processing. + +```markdown +// Bad +The queue uses first-in, first-out processing. + +// Good +The queue works like a waiting line. It processes jobs in the order they arrive. +``` + +If jobs have priorities, the waiting-line image may mislead. Explain that ordering directly. Avoid extended personification and decorative images that make the reader translate back into literal terms. + +### Direct explanation for a familiar audience + +Give the actual rule when the reader already understands the concept. For a developer familiar with queues, an introductory analogy adds little. + +```markdown +// Bad +Think of the queue as a waiting line where jobs patiently wait for their turn. It processes jobs in the order they arrive. + +// Good +The queue processes jobs in the order they arrive. +``` + +### Quotation + +Use a quotation when its exact wording or speaker matters. Attribute and explain it using the available source. Preserve exact words and punctuation. Paraphrase when only the information matters. Here, a supplied interview identifies the missing address instructions as the confusing step. + +```markdown +// Bad +Maya described the process as "confusing". This reveals a profound challenge. + +// Good +Maya described the process as "confusing" because the form did not explain where to enter her address. +``` + +### Direct address + +Use "you" for something the reader can do and "we" only for established shared ground. Useful advice can apply across several products without losing its value. + +```markdown +// Bad +We all know that clarity is important when naming a saved filter. + +// Good +Give your filter a name that describes the tasks it shows. +``` + +## Control pace and emphasis + +### Sentence contrast + +Give explanation enough room, then land a real consequence. Vary pace with the information. Avoid manufacturing a recurring pattern of long sentences and punchy fragments. + +```markdown +// Bad +The first batch failed inspection, resulting in dispatch moving to Thursday, with delivery now being expected on Monday. + +// Good +The first batch failed inspection, so dispatch moved to Thursday. Delivery is now expected on Monday. +``` + +### Parallel phrasing + +Use parallel wording for genuinely comparable items. Keep the natural item count and meaningful order. Do not add a third benefit to create a cadence. + +```markdown +// Bad +You should check the date, confirmation of the address is needed, and then submitting the form comes next. + +// Good +Check the date, confirm the address, and submit the form. +``` + +### Fragment or repetition for emphasis + +Use a fragment, one-sentence paragraph, or repetition only for a clear expressive purpose in the requested genre. Give an emphasis enough context to earn it. A troubleshooting instruction needs complete sentences that preserve actions and conditions. Labels and headings can remain brief because their format supplies their role. + +```markdown +// Bad +Mile twenty-five. First light. One mile left before home. One more mile. One more mile. + +// Good +At mile twenty-five, the first light appeared. I had one mile left before home. + +One more mile. +``` + +### Humour or an aside + +Add humour only when the writer's relationship and subject support it. A familiar personal newsletter may allow a supplied joke that would distract from a complaint response. Keep the message's practical consequence clear. + +```markdown +// Bad +Your replacement charger has decided to take a little holiday. Dispatch has moved to Thursday. + +// Good +I'm sorry your replacement charger is delayed. It will be dispatched on Thursday. +``` + +## Expose structure + +Choose presentation according to how the reader will use the material. + +### Heading + +Name a useful section in a longer piece. Keep it descriptive and follow sentence case. + +```markdown +// Bad + +## Important Information + +Bring proof of address and your appointment letter. + +// Good + +## What to bring to your appointment + +Bring proof of address and your appointment letter. +``` + +### Bullets + +Use bullets for independent items readers need to scan. + +```markdown +// Bad +Bring your passport and your appointment letter and proof of address. + +// Good +Bring these documents: + +- Your passport +- Your appointment letter +- Proof of address +``` + +### Numbers + +Use numbers for a sequence, ranking, or fixed count. + +```markdown +// Bad +First check the date, then confirm the address, then submit the form. + +// Good + +1. Check the date. +2. Confirm the address. +3. Submit the form. +``` + +### Comparison table + +Use a table when readers need to compare common criteria. The literal Markdown below demonstrates that output form. A table should expose the comparison instead of making the reader reconstruct it from repeated sentences. + +```markdown +// Bad +Standard delivery costs £4 and takes three days. Express delivery costs £8 and takes one day. + +// Good + +| Delivery | Cost | Arrival | +| -------- | ---- | ---------- | +| Standard | £4 | Three days | +| Express | £8 | One day | +``` + +### Connected prose + +Use sentences and paragraphs when the reader needs to follow reasoning and qualification. Keep a heading, bullet lead-in, or emphasis when it adds retrieval value. Remove a label that merely repeats the sentence it introduces. + +```markdown +// Bad + +- **Opening:** The library will open on Saturdays. +- **Benefit:** Weekend visitors will have another day to use it. +- **Cost:** Staffing the extra day will cost more. + +// Good +Opening the library on Saturdays gives weekend visitors another day to use it, but staffing the extra day will cost more. +``` diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index b5d9f09..3ee2123 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -1,119 +1,26 @@ --- name: write-skill -description: Creates and revises effective agent skills through confirmed requirements, minimum-sufficient design, and baseline-controlled evaluation. Use when authoring or maintaining a reusable agent skill. -metadata: - type: performer -disable-model-invocation: true +description: Create or refactor reusable agent skills when a recurring task needs specific methods, behaviour, or repeatable operations. --- -# Write Skill +# Write skill -Creates minimum-sufficient agent skills whose observed behaviour justifies their context and execution cost. +Produce a concise skill bundle that reliably performs its **confirmed contract**. Keep it brief without weakening the method, required behaviour, or completion gate. -## Process +## Inputs -### 1. Confirm the contract +Take the recurring task or requested revision from the request. For revisions, inspect the existing bundle and its callers. Retain, rewrite, or delete instructions and resources to meet the confirmed contract. -Inspect the request, an existing skill and its direct composition when revising, and task-scoped evidence without changing the target. Invoke `$elicit-with-context` in a software project and `$elicit` elsewhere to confirm the recurring job or capability gap; task triggers and non-triggers; skill type; inputs and prerequisites; required actions, material branches, authority, and stopping boundary; expected output or handoff; direct composition; necessary resources; and observable success evidence. Keep the target unchanged until elicitation returns the confirmed synthesis. The authoring contract is explicit and closed. +## Method -### 2. Establish the matched baseline +1. **Establish the contract.** Resolve discoverable facts, then invoke [$elicit](../elicit/SKILL.md) for material user-held information and decisions. Propose inputs, outputs, triggers, scope, required behaviour, and observable completion conditions. Recognise methodologies in the user's description and check their fit. Draft only after the complete contract is confirmed. +2. **Choose the structure.** Keep one coherent outcome per skill. Use [the template](assets/skill-template.md) with an overview, Inputs, Method, and Finish. Depart only when a section has no useful job, as in a tiny reference skill, or distinct branches need a router. Keep the purpose and completion gate explicit in either case. +3. **Write direct instructions.** Apply [$write-prose](../write-prose/SKILL.md) to authored prose while preserving the confirmed contract and technical literals. Name the task input and where to obtain it. Include additional inputs only when they govern a concrete action or prerequisite. Remove generic context inventories. Recruit established **leading words**, such as TDD, YAGNI, and decision tree, instead of explaining familiar methods from scratch. State the required intensity and coverage. For example, “ask questions” is weaker than “relentlessly traverse every material branch”. Give defaults, consequential exceptions, and fragile sequences. Leave routine implementation choices to the agent. Prune generic advice. Keep only instructions that change execution, add missing knowledge, or make completion checkable. +4. **Show and package.** Demonstrate important rules that allow competing interpretations. Keep short examples inline and fuller fenced examples in references. Use [writing examples](references/writing.md) to sharpen wording and [the worked examples](references/examples.md) to shape a complete bundle. Keep common essentials in the root and branch detail behind a pointer saying when to read it. Apply **DRY**: give each rule one authoritative home. Reuse tools or bundle tested scripts for repeatable mechanical work. Follow [packaging guidance](references/packaging.md), including `agents/openai.yaml`. +5. **Validate the candidate.** Run [the packaging validator](scripts/validate-skill.js) with `bun /path/to/write-skill/scripts/validate-skill.js /path/to/candidate`. Fix defects and rerun. Follow [scenario testing](references/evaluation.md). A fresh subagent must exercise the candidate on a realistic task, including the reported regression when revising. Inspect actual questions, actions, artefacts, and stopping against the contract. Fix failures and rerun affected checks. Use [token counting](references/tokens.md) to compare plausible wordings. Prefer fewer tokens when clarity, the contract, and scenario behaviour hold. Run applicable repository checks. -Freeze one representative common-path task, harness, tools, permissions, and task-scoped inputs from the confirmed success evidence. Before designing the candidate, run isolated fresh agents: +## Finish -- New skill: no skill. -- Revised skill: no skill and the current skill. +Return the destination, changes, packaging result, scenario and observed behaviour, and remaining limitations. -Record each result, loaded path, output, tool calls, and iterations. Design only against observed failure or excess burden. Stop when no skill fulfils the confirmed behaviour and no current-skill defect, contract change, or burden remains. - -### 3. Bound one capability - -Apply the **KISS principle**: retain the common path and material branches; remove speculative edge cases, unnecessary artefacts, and ceremony that cannot change the evaluated outcome. Keep coupled actions and artefacts together when they serve one outcome. Split independently useful capabilities when their trigger families, outcomes, authority, or success boundaries differ. The candidate has one coherent behavioural purpose. - -Classify the skill by the authority it owns, not by whether it calls tools or fresh agents: - -- A **performer** owns one bounded requested outcome end to end, including actions, artefacts, verification, handoff, and stopping. -- A **router** resolves inputs and coordinates other skills' public contracts, adding only routing unique to the combined outcome. -- A **teaching** skill supplies knowledge and decision rules inside a caller's workflow without owning an independent operation, mutation, artefact, verification, handoff, or stopping decision. -- A **utility** owns one bounded reusable operation and returns its result. - -Set `metadata.type` to exactly `performer`, `router`, `teaching`, or `utility`. Remove responsibilities that belong to another type or split them when each capability is independently useful. - -Choose invocation from actual use. Make regularly useful skills model-invoked. Make occasional, deliberate, or composition-only skills user-invoked. Set `disable-model-invocation` and `agents/openai.yaml` consistently. The skill enters context only through its intended route. - -### 4. Design the loading path - -Use a 1-64 character lowercase name with single hyphen separators and match the directory name. Write the description as one line that starts with a third-person action verb, says what the skill does, includes `Use when`, `Use for`, or `Use to`, and front-loads natural task triggers derived from its content. Describe the skill in isolation as something the agent may select; base its trigger on the work, not whether the user, caller, or another skill invoked it or the current invocation policy. Add a human-readable display name and short description to `agents/openai.yaml`. - -Use **progressive disclosure**: - -- Put concise discovery and invocation metadata in frontmatter and `agents/openai.yaml`. -- Put every-run decisions, actions, authority, branches, and stopping conditions in `SKILL.md`. -- Link conditional detail inline at the branch that needs it. -- Put reusable output material in `assets/`. -- Put deterministic transformations and checks in `scripts/`. - -Keep required coupled guidance together. Prefer direct one-level references. Remove unreachable and unlinked resources. Trace direct composition across trigger, inputs, authority, result, owner, and stopping boundary. A composed skill consumes current caller evidence and loads only missing or stale evidence; an independently invokable skill remains self-sufficient; a fresh agent receives a complete task-scoped packet. A router relies on each invoked skill's public contract and does not repeat its loading, process, or result handling. The smallest sufficient context is reachable when needed. - -### 5. Draft the isolated candidate - -Create the candidate outside the requested destination. For revisions, start from the current bundle and preserve behaviour outside the confirmed change. - -Use [the skill template](assets/skill-template.md). Load [the section guide](references/SECTIONS.md) only when optional sections or subsection layout are needed. Write commands, not essays: - -- Use direct verbs such as _Load_, _Check_, _Run_, _Fix_, _Stop_, and _Return_. -- Match commands to the declared type: performers direct the complete outcome; routers direct only input resolution, invocation, and result routing; teaching skills state principles and decisions for the caller to apply; utilities direct one operation and its result. -- Give each step or subsection one coherent behavioural idea and one observable outcome. -- Use short concrete words and clear fragments; expand conditions, risks, and handoffs that compression could hide. -- State each normative meaning once. Remove filler, hedging, generic knowledge, and repeated enforcement. -- State the intended action first. Retain prohibitions only for essential safety, permission, scope, factual, or deterministic boundaries, paired with the safe action. -- Use a recognised method, principle, theory, or technique only when its canonical name replaces explanation or sharpens a decision, action, or stopping condition. Bold key concepts where they occur naturally. Remove terms that forward testing shows are decorative. -- Match **degrees of freedom** to variability and fragility. Use exact commands or scripts only when the operation requires them. -- Apply **context isolation** to every independently actionable step. Write an explicit fresh-agent step when task-scoped inputs are sufficient and main-thread context is irrelevant or could bias the result; pass only the required inputs and retain only its result. Keep shared understanding, user authority, accumulated state, and process continuity in the main thread. Name the execution boundary instead of leaving delegation optional. -- Give agents a direct result and stopping condition. Add review or feedback only in response to observable evidence, never as recurring ceremony. - -The candidate contains only behaviour-changing instructions and reachable resources. - -### 6. Validate and measure - -Run [scripts/validate-skill.js](scripts/validate-skill.js) and [scripts/measure-context.js](scripts/measure-context.js) with Bun: - -```sh -bun scripts/validate-skill.js /path/to/candidate-skill -bun scripts/measure-context.js /path/to/skill \ - --include references/loaded-reference.md \ - --output /path/to/agent-output.md -``` - -Fix mechanical failures. Repeat `--include` for every reference an arm loaded and `--output` for every arm output; omit unused options. Tokenize a no-skill output through an evaluated bundle and record its discovery and loaded-path cost as zero. Treat exact `o200k_base` counts as comparative evidence, not a target or quality score. Keep discovery metadata, selected path, generated output, and bundle inventory separate. - -### 7. Complete the forward comparison - -Run the candidate on the frozen common-path task in an isolated fresh agent with the same harness, tools, permissions, and task-scoped inputs as the recorded arms. Record its result, loaded path, agent output, tool calls, and iterations. - -Give the anonymised no-skill and candidate results, plus the current-skill result for revisions, to a separate fresh evaluator with only the confirmed behaviour, expected outcome, and efficiency criteria. Require a meaningful behavioural shift over no skill; for revisions, also require preserved or improved behaviour over the current skill. Among behaviourally equivalent candidates, prefer the lower context and execution burden. The candidate's effect is independently evidenced. - -### 8. Refine and publish - -Change the candidate only to correct a specific evaluator failure or remove measured burden, then rerun the affected mechanical and forward checks. Stop when the candidate passes, a smaller equivalent candidate wins, or further change lacks observed justification. - -Publish the passing candidate to the requested destination and rerun validation and measurement there. When the candidate is not justified, keep the existing destination unchanged and return the evidence. The published bundle is the smallest evaluated version that fulfils the confirmed contract. - -## Rules - -- Preserve exact technical meaning: required keywords, paths, commands, API names, error text, safety boundaries, and ordering constraints. -- Treat output tokens, tool calls, and iterations as part of skill cost. Accept extra work only when it changes the required outcome. -- Keep mechanical checks deterministic. Judge semantic force, routing language, useful concepts, and unnecessary ceremony through the forward comparison. - -## Handoff - -Return the destination, confirmed contract, validation result, published files, evaluator verdict, residual uncertainty, and this comparison. Use `n/a` for Current on new skills. Compare Candidate delta with No skill for creation and Current for revision; also state a revision's behavioural shift over No skill. - -| Metric | No skill | Current | Candidate | Candidate delta | -| ----------------------------------------- | -------- | ------- | --------- | --------------- | -| Behavioural result and evaluator evidence | | | | | -| Discovery metadata tokens | | | | | -| Loaded skill-path tokens | | | | | -| Agent output tokens | | | | | -| Tool calls | | | | | -| Iterations | | | | | -| Total measured token burden | | | | | +**Done only when** the bundle matches the confirmed inputs, method, behaviour, and output, packaging passes, and scenario evidence demonstrates its completion gate. Report missing prerequisites or failed checks as blockers. Stop within the requested scope. diff --git a/skills/write-skill/agents/openai.yaml b/skills/write-skill/agents/openai.yaml index e1917b9..a677d58 100644 --- a/skills/write-skill/agents/openai.yaml +++ b/skills/write-skill/agents/openai.yaml @@ -1,5 +1,3 @@ interface: display_name: 'Write Skill' - short_description: 'Author skills through controlled evaluation' -policy: - allow_implicit_invocation: false + short_description: 'Write and validate concise agent skills' diff --git a/skills/write-skill/assets/skill-template.md b/skills/write-skill/assets/skill-template.md index 1db761a..ca7b02e 100644 --- a/skills/write-skill/assets/skill-template.md +++ b/skills/write-skill/assets/skill-template.md @@ -1,15 +1,26 @@ --- -name: skill-name -description: Creates the intended outcome. Use when the skill's confirmed trigger applies. -metadata: - type: performer -disable-model-invocation: true +name: task-specific-name +description: Perform {recognisable task} when {decisive trigger}. --- -# Skill Name +# {Task name} -States what the skill enables in one sentence. +Produce {observable outcome}. Preserve {essential invariant}. -## Process +## Inputs -Describe the minimum-sufficient behaviour in the form best suited to the work. +Take {task input} from {request, caller handoff or named source}. Resolve {material ambiguity or missing prerequisite} before {dependent action}. + +## Method + +1. {Concrete action grounded in the inputs}. +2. {Action and required behaviour, with an explicit bound where premature stopping matters}. +3. {Check the actual output or state}. + +## Finish + +Return {specific output and necessary evidence}. + +**Done only when** {exhaustive, observable completion conditions}. If {blocking condition}, report {exact missing prerequisite}. + + diff --git a/skills/write-skill/package.json b/skills/write-skill/package.json new file mode 100644 index 0000000..0f8195c --- /dev/null +++ b/skills/write-skill/package.json @@ -0,0 +1,7 @@ +{ + "name": "@propulsion/write-skill", + "private": true, + "dependencies": { + "js-tiktoken": "1.0.21" + } +} diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md deleted file mode 100644 index aa1a6a7..0000000 --- a/skills/write-skill/references/SECTIONS.md +++ /dev/null @@ -1,21 +0,0 @@ -# Skill Sections - -Use a section only when it changes execution, constrains the finished result, or transfers responsibility. - -| Order | Section | Use when | Contains | -| ----- | ------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------- | -| 1 | `# Skill Name` | Always | Human-readable skill name. | -| 2 | Introduction | Always | One sentence stating what the skill enables. | -| 3 | `## Prerequisites` | Execution must check conditions before starting | Required state and the action taken when it is absent. | -| 4 | `## Process` | Always | The behaviour that produces the result. | -| 5 | `## Rules` | One invariant governs several steps or the finished result | Cross-cutting constraints stated once. | -| 6 | `## Handoff` | An artefact, decision, or responsibility meaningfully transfers | Recipient, transferred result, evidence, and remaining responsibility. | - -Add another H2 only for a distinct behavioural concern that does not fit this spine. Never create an empty or decorative section. - -Within `## Process`: - -- Use an ordered list or numbered H3s when order changes the result. -- Use H3s when actions can be tested, reordered, or completed independently. -- Keep supporting detail with its action when separation would hide meaning or create a hollow heading. -- Use bullets for independent items, tables for fixed mappings or comparisons, blockquotes for exact authority, and code fences for literal content. diff --git a/skills/write-skill/references/evaluation.md b/skills/write-skill/references/evaluation.md new file mode 100644 index 0000000..67745d1 --- /dev/null +++ b/skills/write-skill/references/evaluation.md @@ -0,0 +1,28 @@ +# Scenario testing + +Test whether the candidate performs its confirmed contract. Packaging and behavioural checks are separate completion requirements. + +## Prepare + +Choose a realistic task with known inputs and an observable expected result. For a revision, include the behaviour that failed. Write the expected questions, actions, output, and stopping condition before running it. For prose or design, use concrete criteria from the user's brief rather than claiming an objective quality score. + +Give a **fresh subagent** the candidate path, task request, raw inputs, necessary tools, and a separate scratch destination. Supply the context a real caller would have, rather than the author's conclusions or expected answer. Keep writes and external actions within the scenario's authorised scope. + +## Exercise and inspect + +Have the subagent use the candidate, including resources its instructions require. For a conversational skill, answer its questions as the scenario user and continue through the completion gate. For an authoring skill, exercise the generated skill too, so a plausible draft does not substitute for the required validation. + +Inspect the actual questions, tool actions, artefacts, and resulting state: + +- Did it use the required inputs and resolve missing prerequisites before dependent work? +- Did it apply the method and exhibit the intended behaviour? +- Did it produce the explicit output with required coverage? +- Did it continue while required work remained and stop at the agreed boundary? + +Check actual file reads when diagnosing missed references. The agent saying it followed the skill is insufficient evidence. Run deterministic checks for mechanical output contracts and changed helpers. + +## Repair and finish + +Fix the instruction, pointer, or helper responsible for a failure, then rerun the affected scenario and packaging checks. Record the scenario, observed result, and material limitations in the handoff. Keep scratch artefacts and test transcripts outside the runtime bundle. + +A successful scenario demonstrates that case. It does not establish universal reliability. Use additional cases when the change or a discovered failure warrants them. Comparative benchmarks and numerical scoring are not required. diff --git a/skills/write-skill/references/examples.md b/skills/write-skill/references/examples.md new file mode 100644 index 0000000..6e5c9fe --- /dev/null +++ b/skills/write-skill/references/examples.md @@ -0,0 +1,65 @@ +# Worked examples + +## A complete workflow + +This illustrative skill has a bounded output, authoritative inputs, concrete coverage, and a completion gate. Its short instructions leave implementation choices open while defining what must be accomplished. It needs no additional references or helpers. + +```markdown +--- +name: reconcile-import-schema +description: Reconcile a CSV import with its supplied JSON schema when fields or types fail validation. +--- + +# Reconcile an import schema + +Produce a proposed mapping and reconciliation report. Preserve the source CSV and schema. Treat declared schema fields and types as authoritative. + +## Inputs + +Use the CSV and schema paths supplied by the caller. Locate a missing file in the stated workspace or ask for its path. Resolve an ambiguous schema version before proposing conversions. + +## Method + +1. Read the schema's fields, types, and required status. Inspect the CSV header and values. +2. Account for every CSV column as mapped, intentionally ignored, or unresolved. Prefer an exact declared match. Propose a renamed match only with supporting evidence. +3. Write `mapping.json`. For each mapped column, record its schema field, any conversion rule, and how invalid values are handled. Keep ambiguous mappings unresolved. +4. Check all rows against the proposed mapping and schema. Use an existing validator when available. Report violations with row numbers and examples. + +## Finish + +Return `mapping.json` and a report containing column coverage, invalid-row counts, unresolved mappings, and the validation command or method. + +**Done only when** every CSV column is accounted for, every proposed schema field exists, and every row has been checked. If a missing input blocks validation, report that input and the dependent work. +``` + +Ship the adapter alongside it: + +```yaml +# agents/openai.yaml +interface: + display_name: 'Reconcile Import Schema' + short_description: 'Reconcile CSV fields against a schema' +``` + +A useful scenario supplies a declared field, a renamed column, an unknown column, and an invalid value beyond the first few rows. Inspect the mapping and report for complete coverage, preserved source files, and the distant invalid row. A plausible header-only mapping would fail the completion gate. + +## A justified tiny layout + +This illustrative reference skill has no ordered operations or special inputs. The purpose, rule, and stopping condition still remain explicit. + +```markdown +--- +name: prefer-guard-clauses +description: Flatten nested control flow when early returns make a function easier to follow. +--- + +# Prefer guard clauses + +Use guard clauses to handle exceptional cases before the main path. Preserve return values, side-effect order, and cleanup. + +Finish when the main path is flat and behaviour is unchanged. Keep nesting where an early return would obscure the logic or bypass cleanup. +``` + +## A router for distinct branches + +A router earns its layout when selecting a branch avoids unrelated instructions. Keep the shared purpose and final outcome explicit. For example, an import router could direct a mapping review to one reference and a failed import repair to another. Each branch must supply its own inputs, method, and completion gate. A short root that loads every branch is not a lean active path. diff --git a/skills/write-skill/references/packaging.md b/skills/write-skill/references/packaging.md new file mode 100644 index 0000000..2e00f84 --- /dev/null +++ b/skills/write-skill/references/packaging.md @@ -0,0 +1,32 @@ +# Packaging + +## Required files + +Every bundle includes `SKILL.md` and `agents/openai.yaml`. + +Start `SKILL.md` with YAML frontmatter: + +| Field | Requirement | +| ------------- | -------------------------------------------------------------------------------- | +| `name` | 1–64 lowercase letters, digits, or single hyphens. Match the directory name. | +| `description` | Non-empty string, at most 1,024 characters. State the task and decisive trigger. | + +Use this minimal OpenAI adapter, replacing the illustrative values: + +```yaml +interface: + display_name: 'Reconcile Import Schema' + short_description: 'Reconcile CSV fields against a schema' +``` + +## Resources and scripts + +Use `references/` for conditional detail and worked examples, `assets/` for templates or copied output material, and `scripts/` for deterministic operations. Name reference files in lowercase with words separated by hyphens, such as `test-doubles.md`. Create only files with a concrete use. Link resources relative to the containing file and state when to reach them. Use called skills' public contracts without restating their procedures. Remove obsolete or orphaned resources and update affected callers. + +Prefer an existing tool over a new helper. Bundle a script when recurring parsing, validation, or transformation can be made repeatable. Document its command, inputs, outputs, runtime, exit codes, and side effects where it is called. Use non-interactive arguments, bounded output, and actionable errors. Make retries idempotent where possible. Test changed helpers on valid and invalid inputs. + +## Validator + +Install the [validator dependencies](tokens.md) once. Use `--help` for the CLI contract. Check destination loading when discovery or invocation changes. + +Errors block packaging. Warnings flag missing or misordered template headings, empty sections, and an unrecognised completion gate for review. A justified tiny or router layout can pass with warnings. Gate wording alone does not prove behaviour. diff --git a/skills/write-skill/references/tokens.md b/skills/write-skill/references/tokens.md new file mode 100644 index 0000000..e9e6f7d --- /dev/null +++ b/skills/write-skill/references/tokens.md @@ -0,0 +1,19 @@ +# Token counting + +Use the [counter](../scripts/count-tokens.js) to compare wording. The packaging validator already reports root and total Markdown counts. + +Requires Bun. Install dependencies once from the repository root with `bun install`, or for a standalone skill: + +```sh +bun install --cwd /path/to/write-skill +``` + +Count candidate text: + +```sh +bun /path/to/write-skill/scripts/count-tokens.js --encoding o200k_base /path/to/candidate/SKILL.md +``` + +Keep the encoding fixed across comparisons. `o200k_base` is a comparison basis, not an exact count for every model. Use `--help` for the CLI contract. + +Compare the root separately from references loaded by a scenario. Unread references cost no active context. The Markdown total describes stored text. These counts do not measure a run's messages, tools, or reasoning. Prefer fewer tokens between equally effective candidates that meet the contract and pass their scenario. No token target overrides required behaviour. diff --git a/skills/write-skill/references/writing.md b/skills/write-skill/references/writing.md new file mode 100644 index 0000000..fca829a --- /dev/null +++ b/skills/write-skill/references/writing.md @@ -0,0 +1,140 @@ +# Writing examples + +These illustrative pairs show how to make an instruction shorter or more exact. The stronger wording must fit the confirmed task. Examples demonstrate a rule, rather than adding another authority for it. + +## Name the task input + +Follow the input rule in [the skill](../SKILL.md). This research example identifies the question to investigate and when clarification matters. + +```markdown +// Before +Use the request, purpose, scope, relevant evidence, available sources, and destination. + +// After +Take the research question or subject from the request. Ask only when missing information would materially change the investigation. +``` + +Keep concrete source-of-truth rules, defaults and prerequisites. For example, a CSV reconciliation skill needs both the CSV and its authoritative schema. Omit an Inputs section when it adds no useful instruction. + +## Recognise the method + +Name an established methodology when its meaning fits the user's description. Keep any task-specific qualification beside it. Here, tests must demonstrate missing behaviour before implementation begins. + +```markdown +// Before +Write some tests before you implement the code. Then make the code work and improve its structure. + +// After +Use **TDD**, one behaviour at a time: red, green, refactor. Observe the test fail for the missing behaviour before implementing it. +``` + +The name recruits familiar knowledge. The final sentence preserves the specific requirement. A label alone cannot supply a local variation or an essential gate. + +## Preserve behavioural force + +Retain the method, persistence, and coverage when revising. In this elicitation example, a plausible first answer must lead to further questioning where material branches remain. + +```markdown +// Before +Ask questions to clarify the user's requirements, then summarise what you understand. + +// After +Relentlessly traverse the **decision tree**, one question at a time. Follow each answer into its dependent branches. Continue until every material branch is resolved, explicitly delegated, or excluded by the agreed scope. +``` + +## Make actions concrete + +Replace a quality adjective with the evidence or action it requires. For this import workflow, the schema owns field names and incomplete mappings must stay visible. + +```markdown +// Before +Carefully reconcile the data and handle problems appropriately. + +// After +Use the schema's declared field names. Account for every CSV column as mapped, intentionally ignored, or unresolved. For each unresolved column, report the conflicting evidence or missing decision. +``` + +## Define the completion gate + +Name the condition that distinguishes done from unfinished. Here, the conversation requires both full branch coverage and confirmed understanding. + +```markdown +// Before +Finish when you have a good understanding of the user's needs. + +// After +**Done only when** every material branch has a supported disposition, a fresh coverage pass opens none, and the user confirms the complete synthesis. An unanswered question leaves its dependent work unresolved. +``` + +Check intermediate stages too. “Observe red before implementation” gives the TDD step a local gate. Add such gates where premature progression would change the result. + +## Give references a trigger + +Tell the agent when the reference becomes useful and what it resolves. + +```markdown +// Before +See references/error-recovery.md for more information. + +// After +Read [error recovery](references/error-recovery.md) when encoding or delimiter errors prevent reading the CSV. +``` + +Keep a non-obvious gotcha inline when the agent would need to know it to recognise the loading condition. + +## Apply DRY to meaning + +Give each instruction one authoritative home. Refer to schemas, configuration, types, and tool help for discoverable facts instead of copying them into prose. Here, the schema already defines the import fields. + +```markdown +// Before +Require customer_id as a string and total as a number. The schema also defines customer_id as a string and total as a number. + +// After +Read the supplied schema for field names, types, and required fields. Validate every row against it. +``` + +A completion gate may refer to the same requirement to define the achieved state. Repeated terminology is not duplicated authority. + +## Keep conditions beside the rule + +Co-locate the action, its conditions, and consequential exceptions. Here, the agent must distinguish a broken input path from a missing decision. + +```markdown +// Before +Ask the user about missing inputs. +Elsewhere: inspect supplied paths first. Ask only if inspection cannot resolve the missing input. + +// After +Inspect supplied paths first. If a required input remains unavailable, ask the user for it before dependent work. +``` + +## State the intended action + +Tell the agent what to do when the boundary matters. Here, an ambiguous mapping must stay visible in the output. + +```markdown +// Before +Do not guess ambiguous mappings. + +// After +Keep ambiguous mappings unresolved and report the missing evidence. +``` + +## Write the discovery description + +Write one sentence naming the task and a decisive “when…” trigger, following [the template](../assets/skill-template.md). Name distinct trigger branches rather than a string of synonyms. Keep execution steps and completion gates in the body. + +```yaml +# Before +description: Help with importing, processing, handling, and managing data effectively. + +# After +description: Reconcile a CSV import with its supplied JSON schema when fields or types fail validation. +``` + +## Format examples for their job + +Use a short inline example when a phrase is enough: “be thorough” → “account for every input column”. Use a fenced block when literal Markdown, a complete instruction, or a before-and-after pair makes the distinction easier to see. Precede it with the rule and enough context to interpret it. Label illustrative facts and placeholders. + +Explain a rule only when its reason changes how the agent applies it. Preserve exact technical literals. diff --git a/skills/write-skill/scripts/count-tokens.js b/skills/write-skill/scripts/count-tokens.js new file mode 100644 index 0000000..ac88843 --- /dev/null +++ b/skills/write-skill/scripts/count-tokens.js @@ -0,0 +1,77 @@ +#!/usr/bin/env bun + +import { getEncoding } from 'js-tiktoken'; +import { readFileSync } from 'node:fs'; +import { parseArgs } from 'node:util'; + +import manifest from '../package.json'; + +export const tokenMetadata = { + encoding: 'o200k_base', + tokenizer: 'js-tiktoken', + tokenizer_version: manifest.dependencies['js-tiktoken'], +}; +const encoders = new Map(); + +export function countTokens(text, encoding = tokenMetadata.encoding) { + if (!encoders.has(encoding)) encoders.set(encoding, getEncoding(encoding)); + return encoders.get(encoding).encode(text, [], []).length; +} + +export function readTextFile(filename) { + return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode( + readFileSync(filename === '-' ? 0 : filename), + ); +} + +export function countFiles(files, encoding) { + const inputs = files.map((input) => ({ + input, + tokens: countTokens(readTextFile(input), encoding), + })); + return { + ...tokenMetadata, + encoding, + inputs, + total_tokens: inputs.reduce((total, input) => total + input.tokens, 0), + }; +} + +if (import.meta.main) { + let options; + try { + options = parseArgs({ + options: { + encoding: { type: 'string' }, + help: { type: 'boolean' }, + }, + allowPositionals: true, + }); + if (options.values.help) { + console.log( + 'Usage: bun count-tokens.js --encoding [files...]\nUTF-8 files; - or no files reads stdin. Outputs JSON. Exits: 0 success, 1 counting failure, 2 usage error.', + ); + process.exit(0); + } + if (!options.values.encoding) + throw new Error('--encoding is required.'); + if (options.positionals.filter((value) => value === '-').length > 1) + throw new Error('stdin may be supplied only once.'); + } catch (error) { + console.error(JSON.stringify({ error: error.message })); + process.exit(2); + } + try { + console.log( + JSON.stringify( + countFiles( + options.positionals.length ? options.positionals : ['-'], + options.values.encoding, + ), + ), + ); + } catch (error) { + console.error(JSON.stringify({ error: error.message })); + process.exitCode = 1; + } +} diff --git a/skills/write-skill/scripts/measure-context.js b/skills/write-skill/scripts/measure-context.js deleted file mode 100644 index 77e2f8c..0000000 --- a/skills/write-skill/scripts/measure-context.js +++ /dev/null @@ -1,347 +0,0 @@ -#!/usr/bin/env bun - -import fs from 'node:fs'; -import path from 'node:path'; -import process from 'node:process'; -import { pathToFileURL } from 'node:url'; - -const args = process.argv.slice(2); -const target = args.shift(); - -if (!target) { - console.error( - 'Usage: bun scripts/measure-context.js [--include relative/path ...] [--output file ...] [--json]', - ); - process.exit(2); -} - -const includes = []; -const outputs = []; -let json = false; - -while (args.length) { - const option = args.shift(); - if (option === '--include') includes.push(args.shift()); - else if (option === '--output') outputs.push(args.shift()); - else if (option === '--json') json = true; - else { - console.error(`Unknown option: ${option}`); - process.exit(2); - } -} - -if ([...includes, ...outputs].some((value) => !value)) { - console.error('--include and --output require a path.'); - process.exit(2); -} - -const root = path.resolve(target); -const rootReal = fs.existsSync(root) ? fs.realpathSync(root) : root; -const skillPath = path.join(root, 'SKILL.md'); -if (!fs.existsSync(skillPath) || !fs.statSync(skillPath).isFile()) { - console.error(`Missing SKILL.md: ${skillPath}`); - process.exit(1); -} -if (!isWithinRoot(skillPath, true)) { - console.error(`SKILL.md resolves outside the skill bundle: ${skillPath}`); - process.exit(1); -} - -function measureText(label, filePath, text) { - return { - label, - path: filePath, - kind: 'text', - tokens: encoder.encode(text).length, - bytes: Buffer.byteLength(text, 'utf8'), - characters: [...text].length, - lines: - text === '' - ? 0 - : text.split(/\r?\n/).length - (/\r?\n$/.test(text) ? 1 : 0), - }; -} - -function isWithinRoot(candidate, resolveSymlinks = false) { - const comparable = resolveSymlinks ? fs.realpathSync(candidate) : candidate; - const base = resolveSymlinks ? rootReal : root; - return comparable === base || comparable.startsWith(`${base}${path.sep}`); -} - -function isInside(base, candidate) { - const relativePath = path.relative(base, candidate); - return relativePath !== '' && !relativePath.startsWith('..'); -} - -function nearestAncestor(startDirectory, matches) { - let directory = path.resolve(startDirectory); - - while (true) { - if (matches(directory)) return directory; - const parent = path.dirname(directory); - if (parent === directory) return null; - directory = parent; - } -} - -function propulsionRoot() { - return nearestAncestor(import.meta.dir, (directory) => { - const manifestPath = path.join(directory, 'package.json'); - if (!fs.existsSync(manifestPath)) return false; - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - return manifest.name === 'propulsion'; - }); -} - -function executionProjectRoot() { - const gitRoot = nearestAncestor(process.cwd(), (directory) => - fs.existsSync(path.join(directory, '.git')), - ); - if (gitRoot) return gitRoot; - - return nearestAncestor(process.cwd(), (directory) => - fs.existsSync(path.join(directory, 'package.json')), - ); -} - -function installedTokenizerEntry() { - const searchRoots = [propulsionRoot(), executionProjectRoot()].filter( - Boolean, - ); - const visited = new Set(); - const foundVersions = new Set(); - - for (const searchRoot of searchRoots) { - if (visited.has(searchRoot)) continue; - visited.add(searchRoot); - const packageRoot = path.join(searchRoot, 'node_modules', 'tiktoken'); - const manifestPath = path.join(packageRoot, 'package.json'); - if (!fs.existsSync(manifestPath)) continue; - - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - if (manifest.version !== '1.0.22') { - foundVersions.add(manifest.version ?? 'an unversioned package'); - continue; - } - - const canonicalRoot = fs.realpathSync(packageRoot); - const entry = fs.realpathSync( - path.join(canonicalRoot, manifest.main ?? 'tiktoken.cjs'), - ); - - if (!isInside(canonicalRoot, entry) || !fs.statSync(entry).isFile()) { - throw new Error('Refusing an invalid installed tiktoken entry.'); - } - - return pathToFileURL(entry).href; - } - - const found = foundVersions.size - ? `; found ${[...foundVersions].join(', ')}` - : ''; - throw new Error( - `Exact context measurement requires tiktoken@1.0.22 installed in Propulsion or the execution project${found}.`, - ); -} - -function readArtifact(absolutePath) { - const buffer = fs.readFileSync(absolutePath); - const binaryExtensions = new Set([ - '.7z', - '.avi', - '.avif', - '.bin', - '.docx', - '.gif', - '.gz', - '.ico', - '.jpeg', - '.jpg', - '.m4a', - '.mov', - '.mp3', - '.mp4', - '.otf', - '.pdf', - '.png', - '.pptx', - '.tar', - '.tgz', - '.ttf', - '.wasm', - '.webp', - '.woff', - '.woff2', - '.xlsx', - '.zip', - ]); - if (binaryExtensions.has(path.extname(absolutePath).toLowerCase())) - return { kind: 'binary', buffer }; - if (buffer.includes(0)) return { kind: 'binary', buffer }; - try { - return { - kind: 'text', - text: new TextDecoder('utf-8', { fatal: true }).decode(buffer), - }; - } catch { - return { kind: 'binary', buffer }; - } -} - -function measureFile(label, absolutePath, displayPath = absolutePath) { - const artifact = readArtifact(absolutePath); - if (artifact.kind === 'binary') { - return { - label, - path: displayPath, - kind: 'binary', - tokens: null, - bytes: artifact.buffer.length, - }; - } - return measureText(label, displayPath, artifact.text); -} - -function readPath(value, base = root, requireInsideRoot = false) { - const absolutePath = path.resolve(base, value); - if (requireInsideRoot && !isWithinRoot(absolutePath)) { - throw new Error( - `Selected-path file is outside the skill bundle: ${absolutePath}`, - ); - } - if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { - throw new Error(`File not found: ${absolutePath}`); - } - if (requireInsideRoot && !isWithinRoot(absolutePath, true)) { - throw new Error( - `Selected-path file resolves outside the skill bundle: ${absolutePath}`, - ); - } - return { absolutePath, artifact: readArtifact(absolutePath) }; -} - -function walkFiles(directory) { - const files = []; - for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { - if (['.git', 'node_modules'].includes(entry.name)) continue; - const absolutePath = path.join(directory, entry.name); - if (entry.isDirectory()) files.push(...walkFiles(absolutePath)); - if (entry.isFile()) files.push(absolutePath); - } - return files; -} - -let encoder; - -try { - const tokenizerEntry = installedTokenizerEntry(); - const { get_encoding: getEncoding } = await import(tokenizerEntry); - encoder = getEncoding('o200k_base'); - const skillText = fs.readFileSync(skillPath, 'utf8'); - const frontmatterMatch = skillText.match( - /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/, - ); - if (!frontmatterMatch) - throw new Error('SKILL.md has no valid frontmatter block.'); - const frontmatter = Bun.YAML.parse(frontmatterMatch[1]); - const discoveryText = `${frontmatter.name}\n${frontmatter.description}`; - const skillBody = skillText.slice(frontmatterMatch[0].length); - - const selectedFiles = [ - measureText('SKILL.md body', 'SKILL.md', skillBody), - ...includes.map((relativePath) => { - const { absolutePath, artifact } = readPath( - relativePath, - root, - true, - ); - if (artifact.kind === 'binary') { - throw new Error( - `Selected-path file is binary and cannot be tokenized: ${relativePath}`, - ); - } - return measureText( - relativePath, - path.relative(root, absolutePath), - artifact.text, - ); - }), - ]; - - const outputFiles = outputs.map((filePath) => { - const { absolutePath } = readPath(filePath, process.cwd()); - return measureFile(path.basename(absolutePath), absolutePath); - }); - - const bundleFiles = walkFiles(root).map((absolutePath) => - measureFile( - path.relative(root, absolutePath), - absolutePath, - path.relative(root, absolutePath), - ), - ); - - const result = { - encoding: 'o200k_base', - scope: 'Exact o200k_base counts for text artefacts; binary artefacts, host wrappers, and hidden instructions are excluded.', - discovery: measureText( - 'name + description', - 'SKILL.md frontmatter', - discoveryText, - ), - selected_path: { - files: selectedFiles, - tokens: selectedFiles.reduce((sum, item) => sum + item.tokens, 0), - }, - generated_output: { - files: outputFiles, - tokens: outputFiles.reduce( - (sum, item) => sum + (item.tokens ?? 0), - 0, - ), - }, - bundle_inventory: { - files: bundleFiles, - tokens: bundleFiles.reduce( - (sum, item) => sum + (item.tokens ?? 0), - 0, - ), - binary_files: bundleFiles.filter((item) => item.kind === 'binary') - .length, - }, - }; - - if (json) { - console.log(JSON.stringify(result, null, 2)); - } else { - console.log(`Encoding: ${result.encoding}`); - console.log(`Scope: ${result.scope}`); - console.log(`Discovery metadata: ${result.discovery.tokens} tokens`); - console.log(`Selected path: ${result.selected_path.tokens} tokens`); - for (const file of result.selected_path.files) - console.log(` ${file.path}: ${file.tokens}`); - if (outputFiles.length) { - console.log( - `Generated output: ${result.generated_output.tokens} tokens`, - ); - for (const file of outputFiles) { - console.log( - ` ${file.path}: ${file.tokens ?? `binary, ${file.bytes} bytes`}`, - ); - } - } - console.log( - `Bundle inventory: ${result.bundle_inventory.tokens} tokens`, - ); - if (result.bundle_inventory.binary_files) { - console.log( - `Binary artefacts excluded: ${result.bundle_inventory.binary_files}`, - ); - } - } -} catch (error) { - console.error(`Measurement failed: ${error.message}`); - process.exitCode = 1; -} finally { - encoder?.free(); -} diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js index 1e8a74a..306a638 100644 --- a/skills/write-skill/scripts/validate-skill.js +++ b/skills/write-skill/scripts/validate-skill.js @@ -1,595 +1,333 @@ #!/usr/bin/env bun -import fs from 'node:fs'; +import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'; import path from 'node:path'; -import process from 'node:process'; -import { pathToFileURL } from 'node:url'; -function nearestAncestor(startDirectory, matches) { - let directory = path.resolve(startDirectory); +import { countTokens, readTextFile, tokenMetadata } from './count-tokens.js'; - while (true) { - if (matches(directory)) return directory; - const parent = path.dirname(directory); - if (parent === directory) return null; - directory = parent; - } +function isMapping(value) { + return value !== null && typeof value === 'object' && !Array.isArray(value); } -function propulsionRoot() { - return nearestAncestor(import.meta.dir, (directory) => { - const manifestPath = path.join(directory, 'package.json'); - if (!fs.existsSync(manifestPath)) return false; - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - return manifest.name === 'propulsion'; - }); +function markdownProse(source) { + let fence = null; + return source + .replace(/|$)/g, '') + .split(/\r?\n/) + .map((line) => { + const marker = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/); + if (marker && !fence) { + fence = marker[1]; + return ''; + } + if ( + marker && + fence && + marker[1][0] === fence[0] && + marker[1].length >= fence.length && + marker[2].trim() === '' + ) { + fence = null; + return ''; + } + return fence ? '' : line.replace(/(`+)[\s\S]*?\1/g, ''); + }) + .join('\n'); } -function executionProjectRoot() { - const gitRoot = nearestAncestor(process.cwd(), (directory) => - fs.existsSync(path.join(directory, '.git')), - ); - if (gitRoot) return gitRoot; - - return nearestAncestor(process.cwd(), (directory) => - fs.existsSync(path.join(directory, 'package.json')), - ); +function isEscaped(source, index) { + let backslashes = 0; + while (index > 0 && source[--index] === '\\') backslashes += 1; + return backslashes % 2 === 1; } -function installedPackageEntry(packageName, expectedVersion) { - const searchRoots = [propulsionRoot(), executionProjectRoot()].filter( - Boolean, - ); - const visited = new Set(); - const foundVersions = new Set(); - - for (const searchRoot of searchRoots) { - if (visited.has(searchRoot)) continue; - visited.add(searchRoot); - const packageRoot = path.join(searchRoot, 'node_modules', packageName); - const manifestPath = path.join(packageRoot, 'package.json'); - if (!fs.existsSync(manifestPath)) continue; - - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - if (manifest.version !== expectedVersion) { - foundVersions.add(manifest.version ?? 'an unversioned package'); +function linkDestination(source, start) { + let cursor = start; + while (/\s/.test(source[cursor] ?? '') && cursor < source.length) + cursor += 1; + if (source[cursor] === '<') { + const end = source.indexOf('>', cursor + 1); + return end < 0 ? null : source.slice(cursor + 1, end); + } + const beginning = cursor; + let depth = 0; + while (cursor < source.length) { + const character = source[cursor]; + if (character === '\\') { + cursor += 2; continue; } - - const canonicalRoot = fs.realpathSync(packageRoot); - const entry = fs.realpathSync( - path.join(canonicalRoot, manifest.main ?? 'index.js'), - ); - const relativeEntry = path.relative(canonicalRoot, entry); - - if ( - relativeEntry === '' || - relativeEntry.startsWith('..') || - !fs.statSync(entry).isFile() - ) { - throw new Error( - `Refusing an invalid installed ${packageName} entry.`, - ); + if (character === '(') depth += 1; + if (character === ')') { + if (depth === 0) break; + depth -= 1; } - - return pathToFileURL(entry).href; + if (/\s/.test(character) && depth === 0) break; + cursor += 1; } - - const found = foundVersions.size - ? `; found ${[...foundVersions].join(', ')}` - : ''; - throw new Error( - `Validation requires ${packageName}@${expectedVersion} installed in Propulsion or the execution project${found}.`, - ); + return depth === 0 ? source.slice(beginning, cursor) : null; } -const semverEntry = installedPackageEntry('semver', '7.8.5'); -const { satisfies, validRange } = await import(semverEntry); - -const target = process.argv[2]; - -if (!target) { - console.error('Usage: bun scripts/validate-skill.js '); - process.exit(2); -} - -const root = path.resolve(target); -const rootReal = fs.existsSync(root) ? fs.realpathSync(root) : root; -const errors = []; - -function fail(message) { - errors.push(message); -} - -function readRequired(relativePath) { - const absolutePath = path.join(root, relativePath); - if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { - fail(`Missing required file: ${relativePath}`); - return null; - } - if (!isWithinRoot(absolutePath, true)) { - fail( - `Required file resolves outside the skill bundle: ${relativePath}`, +function localLinkTargets(source) { + const prose = markdownProse(source); + const targets = []; + const pattern = /!?\[[^\]\n]*\]\(\s*|^ {0,3}\[[^\]\n]+\]:[ \t]*/gm; + for (const match of prose.matchAll(pattern)) { + if (isEscaped(prose, match.index)) continue; + const destination = linkDestination( + prose, + match.index + match[0].length, ); - return null; + const target = destination?.replace(/\\([ ()])/g, '$1').split('#')[0]; + if ( + target && + (/^file:/i.test(target) || + /^[a-z]:[\\/]/i.test(target) || + !/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(target)) + ) + targets.push(target); } - return fs.readFileSync(absolutePath, 'utf8'); + return targets; } -function parseYaml(source, relativePath) { - if (source === null) return null; - try { - const value = Bun.YAML.parse(source); - if (!value || typeof value !== 'object' || Array.isArray(value)) { - fail(`${relativePath} must contain a YAML mapping.`); - return null; - } - return value; - } catch (error) { - fail(`${relativePath} contains invalid YAML: ${error.message}`); - return null; - } +function characterCount(value) { + return Array.from(value).length; } -function analyseMarkdown(source) { - const lines = source.split(/\r?\n/); - let fence = null; - return lines.map((line) => { - const opening = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/); - if (!fence && opening) { - fence = { character: opening[1][0], length: opening[1].length }; - return { raw: line, structural: null, content: false }; - } - const closing = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/); - if ( - fence && - closing && - closing[1][0] === fence.character && - closing[1].length >= fence.length +function layoutWarnings(source) { + const warnings = []; + const prose = markdownProse(source); + const lines = prose.split('\n'); + const content = source.replace(/|$)/g, '').split(/\r?\n/); + const headings = []; + for (let index = 0; index < lines.length; index += 1) { + const atx = lines[index].match(/^ {0,3}(#{1,6})\s+(.+?)\s*$/); + if (atx) { + headings.push({ + level: atx[1].length, + title: atx[2].replace(/\s+#+$/, '').trim(), + start: index, + end: index + 1, + }); + } else if ( + index > 0 && + lines[index - 1].trim() && + /^ {0,3}(?:=+|-+)\s*$/.test(lines[index]) && + headings.at(-1)?.start !== index - 1 ) { - fence = null; - return { raw: line, structural: null, content: false }; + headings.push({ + level: lines[index].trim().startsWith('=') ? 1 : 2, + title: lines[index - 1].trim(), + start: index - 1, + end: index + 1, + }); } - if (fence) - return { raw: line, structural: null, content: line.trim() !== '' }; - return { - raw: line, - structural: line, - content: line.trim() !== '' && !/^#{1,6}\s/.test(line), - }; - }); -} - -function isWithinRoot(candidate, resolveSymlinks = false) { - const comparable = resolveSymlinks ? fs.realpathSync(candidate) : candidate; - const base = resolveSymlinks ? rootReal : root; - return comparable === base || comparable.startsWith(`${base}${path.sep}`); -} - -function stripNonRenderedText(source) { - const withoutComments = source.replace(/|$)/g, ''); - return withoutComments - .split(/\r?\n/) - .map((line) => { - let result = line; - const runs = [...result.matchAll(/`+/g)]; - for (let index = 0; index + 1 < runs.length; index += 2) { - const opening = runs[index]; - const closing = runs - .slice(index + 1) - .find( - (candidate) => - candidate[0].length === opening[0].length, - ); - if (!closing) break; - const start = opening.index; - const end = closing.index + closing[0].length; - result = `${result.slice(0, start)}${' '.repeat(end - start)}${result.slice(end)}`; - } - return result; - }) - .join('\n'); -} - -function markdownLinkTargets(line) { - const targets = []; - for (let index = 0; index < line.length; index += 1) { - if (line[index] !== '[') continue; - let backslashes = 0; - for ( - let cursor = index - 1; - cursor >= 0 && line[cursor] === '\\'; - cursor -= 1 + } + const names = ['Inputs', 'Method', 'Finish']; + const sections = names.map((name) => + headings.find( + (heading) => + heading.level === 2 && + heading.title.toLowerCase() === name.toLowerCase(), + ), + ); + const missing = names.filter((_, index) => !sections[index]); + if (missing.length) + warnings.push( + `SKILL.md: missing default headings: ${missing.join(', ')}. Review whether a tiny or router layout is justified.`, + ); + const present = sections.filter(Boolean); + if ( + present.some( + (section, index) => + index > 0 && section.start < present[index - 1].start, ) - backslashes += 1; - if (backslashes % 2 === 1) continue; - const labelEnd = line.indexOf('](', index + 1); - if (labelEnd < 0) continue; - let depth = 1; - let cursor = labelEnd + 2; - let escaped = false; - for (; cursor < line.length; cursor += 1) { - const character = line[cursor]; - if (escaped) { - escaped = false; - continue; - } - if (character === '\\') { - escaped = true; - continue; - } - if (character === '(') depth += 1; - if (character === ')') depth -= 1; - if (depth === 0) break; - } - if (depth !== 0) continue; - const inside = line.slice(labelEnd + 2, cursor).trim(); - const destination = inside.startsWith('<') - ? inside.slice(1, inside.indexOf('>')) - : inside.match(/^(?:\\.|[^\s])+/)?.[0]; - if (destination) targets.push(destination.replace(/\\([ ()])/g, '$1')); - index = cursor; + ) + warnings.push( + 'SKILL.md: default headings are out of order; use Inputs, Method, Finish unless another layout is justified.', + ); + for (const [index, section] of sections.entries()) { + if (!section) continue; + const next = headings.find( + (heading) => + heading.start > section.start && heading.level <= section.level, + ); + if ( + !content + .slice(section.end, next?.start ?? content.length) + .join('\n') + .trim() + ) + warnings.push( + `SKILL.md: ${names[index]} section is empty; supply content or review whether it has a useful job.`, + ); } - return targets; -} - -function equalStringMaps(left, right) { - const leftKeys = Object.keys(left).toSorted(); - const rightKeys = Object.keys(right).toSorted(); - return ( - leftKeys.length === rightKeys.length && - leftKeys.every( - (key, index) => - key === rightKeys[index] && left[key] === right[key], + if ( + !/\b(?:(?:done|finish(?:ed)?|complete(?:d)?)(?:\s+only)?\s+(?:when|once|after)|stop(?:\s+only)?\s+(?:when|once))\b/i.test( + prose, ) - ); + ) + warnings.push( + 'SKILL.md: no recognisable completion gate; review whether the stopping condition is explicit.', + ); + return warnings; } -function walkFiles(directory) { +function markdownFiles(directory) { const files = []; - for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { + for (const entry of readdirSync(directory, { withFileTypes: true })) { if (['.git', 'node_modules'].includes(entry.name)) continue; - const absolutePath = path.join(directory, entry.name); - if (entry.isDirectory()) files.push(...walkFiles(absolutePath)); - if (entry.isFile()) files.push(absolutePath); + const target = path.join(directory, entry.name); + if (entry.isDirectory()) files.push(...markdownFiles(target)); + else if (entry.isFile() && entry.name.endsWith('.md')) + files.push(target); } return files; } -const skillSource = readRequired('SKILL.md'); -const openaiSource = readRequired('agents/openai.yaml'); - -let frontmatter = null; -let body = ''; - -if (skillSource !== null) { - const match = skillSource.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/); - if (!match) { - fail('SKILL.md must start with YAML frontmatter delimited by ---.'); - } else { - frontmatter = parseYaml(match[1], 'SKILL.md frontmatter'); - body = skillSource.slice(match[0].length); - - const descriptionLine = match[1] - .split(/\r?\n/) - .find((line) => /^description\s*:/.test(line)); - if ( - !descriptionLine || - /^description\s*:\s*[>|]/.test(descriptionLine) - ) { - fail('description must be a single-line YAML scalar.'); - } - } -} - -if (frontmatter) { - const { name, description } = frontmatter; - if (typeof name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) { - fail( - 'name must use lowercase letters or digits with single hyphen separators.', - ); - } else { - if (name.length > 64) fail('name must be 1-64 characters.'); - if (name !== path.basename(root)) - fail('name must match the parent directory name.'); - } - - if (typeof description !== 'string' || description.trim() === '') { - fail('description must be a non-empty string.'); - } else { - if (!/^[A-Z][A-Za-z-]*s\b/.test(description)) { - fail('description must start with a third-person action verb.'); - } - if (!/\bUse (when|for|to)\b/.test(description)) { - fail( - "description must include 'Use when', 'Use for', or 'Use to'.", - ); +function validateOpenAIAdapter(root, errors) { + const filename = path.join(root, 'agents/openai.yaml'); + const fail = (message) => errors.push(`agents/openai.yaml: ${message}`); + try { + const adapter = Bun.YAML.parse(readFileSync(filename, 'utf8')); + if (!isMapping(adapter)) { + fail('must be a YAML mapping.'); + return; } - } - - if (typeof frontmatter['disable-model-invocation'] !== 'boolean') { - fail('disable-model-invocation must be a boolean.'); - } - - const metadata = frontmatter.metadata; - if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) { - fail('metadata must be a YAML mapping.'); - } else { - const allowedTypes = new Set([ - 'performer', - 'router', - 'teaching', - 'utility', - ]); - if (!allowedTypes.has(metadata.type)) { - fail( - 'metadata.type must be performer, router, teaching, or utility.', - ); + if (!isMapping(adapter.interface)) { + fail('interface must be a mapping.'); + } else { + const fields = adapter.interface; + for (const key of ['display_name', 'short_description']) { + if (typeof fields[key] !== 'string' || !fields[key].trim()) + fail(`interface.${key} must be a non-empty string.`); + } } + } catch (error) { + fail(error.message); } } -const openai = parseYaml(openaiSource, 'agents/openai.yaml'); -if (openai) { - if ( - typeof openai.interface?.display_name !== 'string' || - openai.interface.display_name.trim() === '' - ) { - fail('agents/openai.yaml requires interface.display_name.'); - } - const shortDescription = openai.interface?.short_description; +function validateFrontmatter(frontmatter, root, errors) { + const { name, description } = frontmatter; if ( - typeof shortDescription !== 'string' || - shortDescription.length < 25 || - shortDescription.length > 64 + typeof name !== 'string' || + name.length > 64 || + !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) ) { - fail('interface.short_description must be 25-64 characters.'); - } - if (typeof openai.policy?.allow_implicit_invocation !== 'boolean') { - fail( - 'agents/openai.yaml requires boolean policy.allow_implicit_invocation.', + errors.push( + 'name must be 1-64 lowercase letters, digits, or single hyphens, without edge hyphens.', ); + } else if (name !== path.basename(root)) { + errors.push('name must match the skill directory name.'); } if ( - frontmatter && - typeof frontmatter['disable-model-invocation'] === 'boolean' && - typeof openai.policy?.allow_implicit_invocation === 'boolean' && - frontmatter['disable-model-invocation'] === - openai.policy.allow_implicit_invocation - ) { - fail( - 'Claude and OpenAI invocation settings must describe the same invocation mode.', + typeof description !== 'string' || + !description.trim() || + characterCount(description) > 1024 + ) + errors.push( + 'description must be a non-empty string of at most 1,024 characters.', ); - } -} - -if (fs.existsSync(path.join(root, 'agents/openai.yml'))) { - fail('Use agents/openai.yaml, not agents/openai.yml.'); } -if (skillSource !== null) { - if (body.trim() === '') - fail('SKILL.md must contain a non-empty body after frontmatter.'); - - const lines = analyseMarkdown(body); - const headings = []; - lines.forEach(({ structural }, index) => { - const match = structural?.match(/^(#{1,6})\s+(\S.*)$/); - if (match) - headings.push({ - level: match[1].length, - text: match[2].trim(), - line: index, - }); - }); - - const h1s = headings.filter(({ level }) => level === 1); - if (h1s.length !== 1) - fail( - 'SKILL.md must contain exactly one H1 outside fenced code blocks.', - ); - - const processHeadings = headings.filter( - ({ level, text }) => level === 2 && text === 'Process', - ); - if (processHeadings.length !== 1) - fail('SKILL.md must contain exactly one ## Process heading.'); - - if (h1s.length === 1) { - const firstContentLine = lines.findIndex(({ raw }) => raw.trim()); - if (firstContentLine !== h1s[0].line) - fail('The H1 must be the first body content.'); - - const firstH2 = headings.find(({ level }) => level === 2); - const introduction = lines - .slice(h1s[0].line + 1, firstH2?.line ?? lines.length) - .filter(({ raw }) => raw.trim()); - if ( - introduction.length !== 1 || - introduction[0].structural === null || - introduction[0].raw.startsWith('#') - ) { - fail( - 'The H1 must be followed by one non-empty introduction line before the first H2.', +export function validateSkill(directory) { + const root = path.resolve(directory); + const errors = []; + const warnings = []; + const tokenFiles = []; + let frontmatterLength = 0; + validateOpenAIAdapter(root, errors); + try { + const source = readFileSync(path.join(root, 'SKILL.md'), 'utf8'); + const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/); + frontmatterLength = match?.[0].length ?? 0; + if (!match) { + errors.push( + 'SKILL.md must start with YAML frontmatter delimited by ---.', ); + } else { + const frontmatter = Bun.YAML.parse(match[1]); + if (isMapping(frontmatter)) + validateFrontmatter(frontmatter, root, errors); + else errors.push('Frontmatter must be a YAML mapping.'); } + } catch (error) { + errors.push(error.message); } - - const h2s = headings.filter(({ level }) => level === 2); - for (const reserved of ['Prerequisites', 'Process', 'Rules', 'Handoff']) { - if (h2s.filter(({ text }) => text === reserved).length > 1) { - fail(`## ${reserved} may appear at most once.`); - } - } - - const sectionIndex = Object.fromEntries( - h2s.map(({ text }, index) => [text, index]), - ); - if ( - sectionIndex.Prerequisites !== undefined && - sectionIndex.Prerequisites > sectionIndex.Process - ) { - fail('## Prerequisites must appear before ## Process.'); - } - if ( - sectionIndex.Rules !== undefined && - sectionIndex.Rules < sectionIndex.Process - ) { - fail('## Rules must appear after ## Process.'); - } - if (sectionIndex.Handoff !== undefined) { - const lowerBound = sectionIndex.Rules ?? sectionIndex.Process; - if (sectionIndex.Handoff < lowerBound) - fail( - '## Handoff must appear after ## Process and ## Rules when present.', - ); - } - - for (let index = 0; index < headings.length; index += 1) { - const heading = headings[index]; - const next = headings - .slice(index + 1) - .find(({ level }) => level <= heading.level); - const content = lines - .slice(heading.line + 1, next?.line ?? lines.length) - .some(({ content: hasContent }) => hasContent); - if (!content) fail(`Heading '${heading.text}' has no content.`); - } -} - -if (fs.existsSync(root)) { - const files = walkFiles(root); - const markdownFiles = files.filter((file) => file.endsWith('.md')); - const linkedFromSkill = new Set(); - - for (const file of markdownFiles) { - const source = fs.readFileSync(file, 'utf8'); - const linkSource = file === path.join(root, 'SKILL.md') ? body : source; - for (const { structural } of analyseMarkdown( - stripNonRenderedText(linkSource), - )) { - if (structural === null) continue; - for (const linkTarget of markdownLinkTargets(structural)) { - const rawTarget = linkTarget.trim().split('#')[0]; - if (!rawTarget || /^(?:[a-z]+:|#)/i.test(rawTarget)) continue; - const resolved = path.resolve( - path.dirname(file), - decodeURIComponent(rawTarget), - ); - if (!isWithinRoot(resolved)) { - fail( - `${path.relative(root, file)} links outside the skill bundle: ${rawTarget}`, - ); - continue; - } - if (!fs.existsSync(resolved)) { - fail( - `${path.relative(root, file)} links to missing path: ${rawTarget}`, + try { + for (const file of markdownFiles(root).toSorted()) { + const content = readTextFile(file); + tokenFiles.push({ + file: path.relative(root, file), + tokens: countTokens(content), + }); + const prose = + file === path.join(root, 'SKILL.md') + ? content.slice(frontmatterLength) + : content; + if (file === path.join(root, 'SKILL.md')) + warnings.push(...layoutWarnings(prose)); + for (const target of localLinkTargets(prose)) { + const decoded = decodeURIComponent(target); + if ( + /^file:/i.test(decoded) || + path.isAbsolute(decoded) || + path.win32.isAbsolute(decoded) + ) { + errors.push( + `${path.relative(root, file)} links to an absolute local path: ${target}. Use a relative resource link.`, ); continue; } - if (!isWithinRoot(resolved, true)) { - fail( - `${path.relative(root, file)} links through a symlink outside the skill bundle: ${rawTarget}`, + const resolved = path.resolve(path.dirname(file), decoded); + if (!existsSync(resolved)) + errors.push( + `${path.relative(root, file)} links to missing path: ${target}`, ); - continue; - } - if (file === path.join(root, 'SKILL.md')) - linkedFromSkill.add(resolved); - } - } - } - - for (const file of files.filter((candidate) => - candidate.startsWith(path.join(root, 'references') + path.sep), - )) { - if (!linkedFromSkill.has(file)) { - fail( - `Reference must be linked directly from SKILL.md: ${path.relative(root, file)}`, - ); - } - } - - const packagePath = path.join(root, 'package.json'); - if (fs.existsSync(packagePath)) { - let packageJson = null; - try { - packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8')); - } catch (error) { - fail(`package.json contains invalid JSON: ${error.message}`); - } - const lockPath = path.join(root, 'package-lock.json'); - if (!fs.existsSync(lockPath)) { - fail('package-lock.json is required when package.json exists.'); - } else { - try { - const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8')); - const lockRoot = lock.packages?.['']; - if (![2, 3].includes(lock.lockfileVersion) || !lockRoot) { - fail( - 'package-lock.json must use lockfileVersion 2 or 3 and contain a root package entry.', + else if ( + !statSync(resolved).isFile() && + !statSync(resolved).isDirectory() + ) + errors.push( + `${path.relative(root, file)} links to an unreadable resource: ${target}`, ); - } else if (packageJson) { - if ( - lockRoot.name !== packageJson.name || - lockRoot.version !== packageJson.version - ) { - fail( - 'package-lock.json root name and version must match package.json.', - ); - } - const declared = packageJson.dependencies ?? {}; - const locked = lockRoot.dependencies ?? {}; - if (!equalStringMaps(declared, locked)) { - fail( - 'package-lock.json root dependencies must match package.json.', - ); - } - for (const dependency of Object.keys(declared)) { - const entry = - lock.packages?.[`node_modules/${dependency}`]; - if (!entry?.version) { - fail( - `package-lock.json lacks a complete entry for dependency: ${dependency}`, - ); - continue; - } - const range = validRange(declared[dependency]); - if ( - range && - !satisfies(entry.version, range, { - includePrerelease: true, - }) - ) { - fail( - `package-lock.json version for ${dependency} does not satisfy package.json.`, - ); - } - if ( - entry.resolved?.startsWith('http') && - !/^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/.test( - entry.integrity ?? '', - ) - ) { - fail( - `package-lock.json has invalid integrity for dependency: ${dependency}`, - ); - } - } - } - } catch (error) { - fail( - `package-lock.json contains invalid JSON: ${error.message}`, - ); } } + } catch (error) { + errors.push(error.message); } + return { + skill: root, + valid: errors.length === 0, + errors, + warnings, + tokens: { + ...tokenMetadata, + files: tokenFiles, + root_tokens: + tokenFiles.find((file) => file.file === 'SKILL.md')?.tokens ?? + null, + markdown_tokens: tokenFiles.reduce( + (total, file) => total + file.tokens, + 0, + ), + }, + }; } -if (errors.length) { - console.error('Status: invalid'); - for (const error of errors) console.error(`- ${error}`); - process.exit(1); +if (import.meta.main) { + const args = process.argv.slice(2); + if (args.length === 1 && args[0] === '--help') { + console.log( + 'Usage: bun validate-skill.js \nChecks required metadata and relative local Markdown links. Reports advisory root layout and completion-gate warnings plus o200k_base Markdown token counts. Warnings do not affect validity. Exits: 0 valid, 1 invalid, 2 usage error.', + ); + } else if (args.length !== 1 || args[0].startsWith('--')) { + console.error('Usage: bun validate-skill.js '); + process.exitCode = 2; + } else { + const result = validateSkill(args[0]); + console.log(JSON.stringify(result, null, 2)); + process.exitCode = result.valid ? 0 : 1; + } } - -console.log(`Status: valid\nSkill: ${root}`);