Add .claude/skills continuity library for maintainers#2778
Draft
spawnia wants to merge 2 commits into
Draft
Conversation
Introduce a 15-skill library under .claude/skills/ to let junior/mid-level engineers and smaller AI models maintain, debug, extend, and advance Lighthouse without loss of standard. Core: change-control, debugging-playbook, failure-archaeology, architecture-contract, graphql-laravel-reference, config-and-flags, build-and-env, testing-and-qa, diagnostics-and-tooling (with runnable scripts/), docs-and-writing, issue-triage-and-reproduction. Advanced: v7-campaign (decision-gated major-release runbook), proof-and-analysis-toolkit, research-frontier, research-methodology. Every command, flag, path, commit, and claim verified against the repo at v6.68.0. Volatile facts are date-stamped with re-verification commands. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Hvx6ybvjs3XU8TeHchLswP
There was a problem hiding this comment.
Pull request overview
Adds a new .claude/skills “continuity library” intended to capture Lighthouse maintainer workflows (release/change control, testing/QA, diagnostics, debugging, research, and issue triage) plus a few helper scripts referenced by the skills.
Changes:
- Introduces 15 new skill documents under
.claude/skills/to document maintainer processes and repository-specific conventions. - Adds 3 helper scripts (schema diff, config-key extraction, benchmark report capture) under
.claude/skills/lighthouse-diagnostics-and-tooling/scripts/. - Codifies a v7 release campaign plan and related proof/QA gates as structured, reusable playbooks.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| .claude/skills/lighthouse-v7-campaign/SKILL.md | v7 release campaign plan with inventory, cut-list, execution order, and release gates |
| .claude/skills/lighthouse-testing-and-qa/SKILL.md | Testing conventions, suite anatomy, and evidence requirements |
| .claude/skills/lighthouse-research-methodology/SKILL.md | Research discipline and evidence bar for investigations |
| .claude/skills/lighthouse-research-frontier/SKILL.md | Candidate long-horizon projects framed as falsifiable bets |
| .claude/skills/lighthouse-proof-and-analysis-toolkit/SKILL.md | Proof recipes for laziness, BC, N+1, perf, races, memory, upstream-vs-local |
| .claude/skills/lighthouse-issue-triage-and-reproduction/SKILL.md | Issue triage flow and reproduction-as-test runbook |
| .claude/skills/lighthouse-failure-archaeology/SKILL.md | Chronicle of historical incidents/reverts/settled decisions to avoid rework |
| .claude/skills/lighthouse-docs-and-writing/SKILL.md | Docs-of-record guidance and house writing style/templates |
| .claude/skills/lighthouse-diagnostics-and-tooling/SKILL.md | Measurement/tooling catalog (artisan, benchmarks, schema diffs, phpstan) |
| .claude/skills/lighthouse-diagnostics-and-tooling/scripts/schema-diff.sh | Script to diff printed schema across two git refs |
| .claude/skills/lighthouse-diagnostics-and-tooling/scripts/config-keys.php | Tokenizer-based config key lister for src/lighthouse.php |
| .claude/skills/lighthouse-diagnostics-and-tooling/scripts/bench-report.sh | Script to run PHPBench and save timestamped reports |
| .claude/skills/lighthouse-debugging-playbook/SKILL.md | Symptom→cause triage guide for common runtime/test failures |
| .claude/skills/lighthouse-config-and-flags/SKILL.md | Catalog of config keys/env vars and how to add new options safely |
| .claude/skills/lighthouse-change-control/SKILL.md | Change classification/gating rules (SemVer, @api, schema-consumer stability) |
| .claude/skills/lighthouse-build-and-env/SKILL.md | Environment setup and operational traps (Docker/Make/native, CI deltas) |
| .claude/skills/lighthouse-architecture-contract/SKILL.md | Load-bearing architectural decisions/invariants and known weak points |
| .claude/skills/graphql-laravel-reference/SKILL.md | Repo-specific GraphQL/Laravel domain reference (directives, federation, tracing, etc.) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| php artisan lighthouse:print-schema --sort > after.graphql | ||
| diff -u before.graphql after.graphql | ||
| ``` | ||
| Interpretation: **empty diff = non-breaking for consumers** (the hard rule). Any removed field/type, changed nullability, or changed default is breaking. Use `scripts/schema-diff.sh` to do this across two git refs automatically. |
| - `HugeRequestBench` — large request parsing cost. | ||
| - `ASTUnserializationBench` — schema-cache AST unserialize cost (relevant to #2771/schema cache work). | ||
|
|
||
| Interpretation discipline: run on the **same machine**, look at the **`rstdev`** (relative standard deviation) column before trusting any delta — a change smaller than rstdev is noise. Baseline first, change, re-run; explain every regression. Use `scripts/bench-report.sh before` / `... after` to capture dated reports. |
Comment on lines
+92
to
+93
| ## Shipped scripts (`scripts/`) | ||
|
|
Comment on lines
+94
to
+98
| | Script | Purpose | Verified | | ||
| |---|---|---| | ||
| | `schema-diff.sh <ref-before> <ref-after>` | Diff printed schema across two git refs; non-empty diff fails. | `bash -n` OK 2026-07-07 (not executed — needs vendor/). | | ||
| | `config-keys.php [path]` | Tokenizer-based list of config keys in `src/lighthouse.php` (no Laravel boot). | Executed with PHP 8.4 on 2026-07-07 — prints the keys. | | ||
| | `bench-report.sh [label]` | Run PHPBench, tee to a dated `bench-reports/` file. | `bash -n` OK 2026-07-07 (not executed — needs vendor/). | |
| ## 3. Prove schema backward compatibility | ||
|
|
||
| - **Goal:** show a change does not break schema consumers. | ||
| - **Method:** `lighthouse:print-schema --sort` before and after (or across two git refs via `scripts/schema-diff.sh`); diff. |
Comment on lines
+8
to
+10
| * bare `require` fatals outside a Laravel app. This parses the file with the PHP | ||
| * tokenizer and prints every single-quoted string that is immediately followed by | ||
| * `=>` (i.e. array keys), which approximates the config option names. |
Comment on lines
+12
to
+14
| * Usage: | ||
| * php scripts/config-keys.php [path/to/lighthouse.php] | ||
| * Default path: src/lighthouse.php relative to the current directory. |
Comment on lines
+8
to
+11
| # Usage (run from a Laravel APP that uses Lighthouse, or adapt PHPUNIT path for a fixture app): | ||
| # scripts/schema-diff.sh <ref-before> <ref-after> | ||
| # scripts/schema-diff.sh master HEAD | ||
| # |
Comment on lines
+24
to
+25
| TMPDIR="$(mktemp -d)" | ||
| trap 'rm -rf "$TMPDIR"' EXIT |
Comment on lines
+8
to
+11
| # Usage: | ||
| # scripts/bench-report.sh [label] | ||
| # scripts/bench-report.sh before | ||
| # scripts/bench-report.sh after |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The result of what Fable 5 (+ Opus 4.8 after my usage limit blew out) did with https://github.com/tomicz/fable-5-train-opus-skills-after-it-retires.
Will definitely not merge as-is, but might use bits and pieces.