Merge pull request #93 from lightspeedwp/claude/config-docs-template-016SXALgwqRUX9zDYQMAuevf

Create documentation template for tool configuration

Author: ashleyshaw

docs/HUSKY-PRECOMMITS.md

@@ -1,90 +1,106 @@
-# Husky Pre-Commit Hooks Documentation
+---
+title: "Husky Pre-commit Hooks"
+description: "Using Husky to enforce quality gates (linting/tests) before commits"
+last_updated: "2025-11-14"
+version: "1.0"
+maintainers: ["LightSpeed DevOps"]
+tags: ["husky", "pre-commit", "automation", "linting"]
+---
 
-This document explains the Husky pre-commit setup, usage, and best practices for this repository. It is designed to be used alongside [LINTING.md](./LINTING.md), which details the linting tools and configuration.
+# Husky Pre-commit Hooks
 
----
+**`docs/HUSKY-PRECOMMITS.md`** – *Pre-commit Hook as Quality Gate*
 
-## Linting & Quality Checks
+We use **Husky** to run linting and formatting checks locally before code is committed, serving as a "first line" quality gate. This ensures that by the time code reaches CI, it has already passed basic standards.
 
-Husky is tightly integrated with our linting workflow. For a full list of linting tools, configuration files, and what is checked before each commit, see [LINTING.md](./LINTING.md). This ensures that all code meets our standards before it is committed.
+## Status and Rationale
 
----
+**Status:** *Implemented in develop (pending merge to main).* Previously, Husky was not set up in this repo, meaning developers could commit code that failed our style/test checks. We've now added a Husky *pre-commit* hook to mirror the checks that run in CI, closing this gap.
+
+**Why Husky:** Running checks locally speeds up feedback. It prevents "easy" issues (like code style or obvious test failures) from ever reaching the repo, which reduces CI failures and iteration time. This aligns with our goal that *"files are linted properly and tests pass"* before pushing.
+
+## Installation
 
-## Overview
+Husky is managed as a dev dependency. To install and enable Husky in a fresh clone:
 
-Husky is used to enforce code quality and consistency by running automated checks (such as linting and tests) before code is committed. This helps prevent errors and maintain standards across the codebase.
+1. After running `npm install` (or `npm ci`), activate Husky hooks:
 
-## .husky Folder Structure
+```bash
+npx husky install
+```
+
+This installs Git hooks into the local repo's `.husky/` directory (already present in source).
+
+2. Verify that a `.husky/pre-commit` file exists with our hook. It should have been created in the repo (or by the install command).
 
-- `.husky/` — Contains all Husky hook scripts
-  - `pre-commit` — Main pre-commit hook script (runs linting, tests, etc.)
-  - `commit-msg` — Validates commit message format (if present)
-  - Other hooks as needed (e.g., `pre-push`)
+If Husky isn't working, ensure Git isn't bypassing hooks (no `--no-verify` flag used) and that you have the correct Node version. We specify Node version in `.nvmrc` to avoid incompatibilities (our CI uses the same Node version).
 
-## How Pre-Commit Works
+## Pre-commit Hook Behavior
 
-When you run `git commit`, Husky automatically executes the scripts in `.husky/pre-commit` before the commit is finalized. If any check fails, the commit is aborted.
+Our pre-commit hook is defined in **`.husky/pre-commit`**. It runs our formatting and linting checks before allowing a commit. In summary, it will:
 
-## Bypassing Pre-Commit Hooks
+- **Format code** (auto-fix) by running **`npm run format`**.
+- **Run linters and tests** by running **`npm run check`** (a composite script that runs all linters and unit tests).
 
-To bypass Husky pre-commit hooks (not recommended except for emergencies):
+If *either* of those steps fails, the commit is aborted. You must fix the issues and try again. This prevents committing code that would fail CI.
 
-```sh
-git commit --no-verify
+Below is the content of our `.husky/pre-commit` file for reference:
+
+```bash
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run format && npm run check
 ```
 
-> **Note:** Use this only if you have a valid reason. All skipped checks must be run manually before pushing.
+This uses Husky's shell script shim and then runs our tasks. The `&&` ensures that if formatting fails or leaves changes, or if any check fails, the process halts with a non-zero exit (blocking the commit).
 
-## Suppression Storage & Management
+## Adding Husky to an Existing Clone
 
-- Husky does not store suppressions by default. If you bypass a hook, it is not recorded.
-- If you want to re-enable hooks, simply commit as normal (without `--no-verify`).
-- To update or remove a hook, edit or delete the relevant script in `.husky/`.
+If you already have the repo and just pulled the updated config, run `npm install` (to get Husky) and then `npx husky install` to set up the hooks. This is a one-time step per clone. After that, Git will trigger the hook on commits automatically.
 
-## Recommended Commands
+## Ignoring Specific Files or Bypassing
 
-- **Install Husky hooks:**
+Our goal is to run the hook on all source changes. However, large binary files or documentation-only changes shouldn't block a commit on lint rules:
 
-    ```sh
-    npx husky install
+- Husky will only lint the files you're committing (through our `npm run ...` scripts configuration). For instance, if you edit only Markdown, JS lint won't run, etc.
+- If absolutely necessary (e.g. an urgent hotfix), you can bypass hooks with `git commit --no-verify`. **Use this sparingly.** Bypassing means CI will catch any issues later.
 
-    ```
+We intentionally do not run lengthy end-to-end tests on pre-commit (those run in CI), to keep commits fast. The pre-commit focuses on quick checks (formatting, linters, unit tests). This strikes a balance between safety and speed.
 
-- **Add a new hook:**
+## CI Integration
 
-    ```sh
-    npx husky add .husky/pre-commit "npm run lint:js && npm run lint:css && npm run lint:md && npm test"
+The pre-commit hook runs the same `npm run check` that CI does. In our GitHub Actions CI, we also execute the full test suite on push. The idea is "fail fast, locally":
 
-    ```
+- By the time CI runs, code should already be formatted and pass linting. CI then mainly validates integration (and runs heavier tests).
+- If a contributor bypasses Husky (or Husky wasn't installed), the CI will still fail on the same `npm run check` script in our workflow, acting as a safety net.
 
-- **Bypass hooks:**
+Having duplicate checks may seem redundant, but it's intentional. It virtually eliminates trivial CI failures (saving time) and acts as a double-insurance policy.
 
-    ```sh
-    git commit --no-verify
-    ```
+## Setup Commands (for reference)
 
-## Getting Started
+For maintainers, these were the steps used to set up Husky in this repo:
 
-1. Run `npm install` to install dependencies (including Husky).
-2. Run `npx husky install` to set up hooks (usually done automatically on install).
-3. Commit as usual — Husky will run checks before each commit.
+```bash
+npm install --save-dev husky   # Add Husky to devDependencies
+npx husky install             # Install Git hooks (creates .husky/ folder)
+npx husky add .husky/pre-commit "npm run format && npm run check"
+```
 
-## Best Practices
+This added the pre-commit file with the content shown above. Our `package.json` already had the necessary `format` and `check` scripts defined (mapping to Prettier/ESLint and our test runner).
 
-- Do not bypass hooks unless absolutely necessary.
-- Keep hook scripts up to date with project standards.
-- Review and update hooks as new linting or test scripts are added.
-- See [docs/LINTING.md](./LINTING.md) for details on what is checked by each hook.
+*(No changes are needed to developers' workflows aside from running `npm install` and having Node per `.nvmrc`. Commits are now gated, improving code quality upstream.)*
 
 ## Related Files & Further Reading
 
 - [docs/LINTING.md](./LINTING.md) — Linting tools and configuration
-- [docs/HUSKY-LINITING-TASKS.md](./HUSKY-LINITING-TASKS.md) — Task list for Husky and linting documentation
+- [docs/METRICS.md](./METRICS.md) — Metrics and telemetry
+- [docs/config/workflow-husky.md](./config/workflow-husky.md) — Detailed Husky configuration
 - [package.json](../package.json) — NPM scripts run by hooks
-- [.husky/](../../.husky/) — Actual hook scripts
+- [.husky/](../.husky/) — Actual hook scripts
 
 ---
 
-### Last updated
+### Last Updated
 
-24 October 2025
+2025-11-14

docs/METRICS.md

@@ -1,5 +1,75 @@
+---
+title: "Metrics & Telemetry"
+description: "Defining key quality metrics and our telemetry policy"
+last_updated: "2025-11-14"
+version: "1.0"
+maintainers: ["LightSpeed Engineering Ops"]
+tags: ["metrics", "telemetry", "CI", "analytics"]
+---
+
 # Metrics & Telemetry
 
-- **What we track:** CI failure mix, PR time-to-merge, non-semantic diff ratio, docs↔scripts parity errors, schema test coverage, lint rule churn.
-- **How:** Weekly workflow `ci-metrics.yml` → `scripts/gather-metrics.js`.
-- **Telemetry:** No local collection by default; any local telemetry is opt-in and documented.
+**`docs/METRICS.md`** – *Metrics & Telemetry Definition*
+
+To continuously improve our processes, we track certain **development metrics**. These help us quantitatively verify that our community health files and automations are delivering value. Below we define what we measure (and what we **don't** measure):
+
+## Key Metrics Tracked
+
+- **CI Failure Breakdown:** We categorize CI failures by type. For example, how many pipeline failures are due to formatting/lint issues vs. test failures vs. other causes. This helps identify if our pre-commit checks are effective (in an ideal state, CI failures from linting should approach zero).
+- **Pre-commit vs CI Catch Rate:** We monitor how often our Husky pre-commit hook prevents an issue *before* CI. If something slips to CI that Husky should catch (e.g. a lint error), that indicates a gap. Our goal is a high pre-commit "pass rate" – meaning most commits meet quality standards, and CI failures are rare and usually for more complex issues.
+- **PR Cycle Time:** The average time from PR open to merge. Since our automation (like issue templates, labeling, and pre-commit checks) aims to reduce friction, a decreasing PR cycle time (or time-to-merge) is a positive signal. We'll track median and 90th percentile times.
+- **Non-Functional Churn (Formatting Noise):** We measure what percentage of lines changed in a PR are purely formatting/styling (non-functional changes). A low percentage means developers have fewer "noise" changes – indicating that auto-formatting is being applied consistently. High values might mean folks need to run `npm run format` more often.
+- **Lint Rule "Churn":** Each quarter, we'll review how many lint rules were added, removed, or disabled. Frequent rule changes may indicate instability in standards; our goal is a fairly stable lint baseline (with planned updates, not constant toggling).
+
+Each metric is collected via scripts or the GitHub API and aggregated in a periodic report.
+
+## Collection Method
+
+A GitHub Action workflow (see **ci-metrics.yml** in workflows) runs on a schedule (weekly). It uses a custom Node script to gather data:
+
+- For CI failures: It pulls recent workflow runs and tallies failure reasons (by parsing logs or using GitHub's run conclusion and job names).
+- For PR cycle time: It queries recent closed PRs' open-to-merge intervals.
+- For formatting churn: It scans merged PR diffs to calculate the ratio of whitespace/style-only changes (this requires parsing diffs; we approximate via known patterns).
+- For lint rule churn: It looks at our ESLint/Stylelint config changes or count of `eslint-disable` comments added in the codebase over time.
+
+The results are output as a Markdown summary (and in the future, maybe as an issue or dashboard). **Owner: Engineering Ops** will review this report quarterly and identify any action items (e.g. an uptick in formatting noise might prompt a reminder to developers to run Prettier, or an adjustment in our tools).
+
+## Sample Metrics Report (illustrative)
+
+- **This Week's CI Failures:** 10 total – *6 from unit tests, 4 from linting.* (👍 lint issues down from 10 last week, indicating Husky is working.)
+- **Pre-commit Hook Effectiveness:** 95% of pushes had no CI lint errors (i.e. Husky caught issues locally). 5% of pushes had lint problems in CI *(likely Husky was skipped or a new rule was added)*.
+- **Median PR Cycle Time:** 2.1 days (from open to merge). *Down from ~3 days last quarter – possibly due to better issue templates and automated labeling.*
+- **Formatting Churn:** 8% of lines changed in PRs were non-functional (formatting or comments). *This is relatively low, suggesting developers are using the auto-formatting tools.*
+- **Lint Rule Churn:** 2 ESLint rules tweaked this quarter, 1 new Markdownlint rule added. *All were part of planned updates (see Changelog). No excessive rule thrash.*
+
+These numbers will be tracked over time to spot trends.
+
+## Telemetry Policy
+
+**No personal telemetry is collected.** We do **not** track individual usage of editors or any keystroke data. Our focus is on repository-level metrics (as described above) and outcomes like CI results or PR durations.
+
+- **Editor/IDE Telemetry:** We do not gather any data from user editors (e.g. we do *not* use VS Code or Copilot telemetry for this). While VS Code's MCP extension can provide some insights, we have chosen not to enable any tracking there by default.
+- **Optional Future Telemetry:** If we introduce a local tool to measure, for example, how often certain AI **instructions** are triggered or used, it will be strictly opt-in. We would clearly document how to enable it and what is collected, and it would never include sensitive or personally identifiable information.
+- **Data Handling:** Metrics collected by our scripts (as outlined in the **Collection Method** section) are aggregated and used internally to improve our tooling. They do not include contributor identities (we anonymize or focus on aggregates).
+- **Retention:** Metrics reports will be kept for trend analysis (likely in a `metrics/` directory or as issues). Raw data (e.g. API query results) is not stored long-term.
+
+In summary, our approach to telemetry is *conservative*: we measure what we need to improve dev workflows and nothing more. We respect developer privacy and adhere to GitHub's policies (no tracking beyond our repo boundaries without consent).
+
+## Outcome Tracking
+
+Over time, these metrics will tell us if our efforts are paying off. For example, if we see PR times dropping and fewer CI fails, that validates the efficiency gains we expected. Conversely, any negative trends will prompt investigation (perhaps via a retro or by adding an agent to assist). Metrics give us a feedback loop to continuously adjust our automation and documentation.
+
+*(The Metrics Action is set up but initial data will be sparse. The first full report is expected next quarter as we accumulate data.)*
+
+## Related Files & Further Reading
+
+- [docs/HUSKY-PRECOMMITS.md](./HUSKY-PRECOMMITS.md) — Pre-commit hooks setup
+- [docs/LINTING.md](./LINTING.md) — Linting strategy and tools
+- [.github/workflows/ci-metrics.yml](../.github/workflows/ci-metrics.yml) — Metrics collection workflow
+- [scripts/gather-metrics.js](../scripts/gather-metrics.js) — Metrics gathering script
+
+---
+
+### Last Updated
+
+2025-11-14

docs/config/README.md

@@ -111,14 +111,32 @@ All configuration documentation in this directory follows these standards:
 - **Troubleshooting**: Common issues and solutions
 - **Cross-References**: Links to related configurations and documentation
 
+### Documentation Template
+
+All configuration documentation follows the standardized template defined in:
+
+- **[Tool Configuration Documentation Template](./tools.instructions.md)** - Blueprint for all config documentation
+
+This template ensures consistency across all tool configuration files and includes:
+- Purpose and scope
+- When and how the tool runs
+- Exact scripts and commands
+- Severity and failure modes
+- Suppression and ignoring strategies
+- Version pinning and reproducibility
+- Maintenance ownership and review cadence
+- ROI vs cost analysis
+- References and further reading
+
 ## Contributing
 
 When adding new configuration documentation:
 
-1. Follow the template structure from existing files
+1. Follow the **[Tool Configuration Documentation Template](./tools.instructions.md)**
 2. Include practical examples and use cases
 3. Document integration with other tools
 4. Update this index file with the new configuration
 5. Cross-reference in related documentation
+6. Ensure all npm script references are validated by `scripts/verify-docs-commands.js`
 
 See [Contributing Guidelines](../../CONTRIBUTING.md) for more details.