Skip to content

Commit 4990735

Browse files
martincjarvismartincjarvis
committed
docs: add repo standards gap analysis
1 parent 3e4649c commit 4990735

3 files changed

Lines changed: 118 additions & 1 deletion

File tree

‎cspell.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,9 @@
6666
"Summarise",
6767
"artefacts",
6868
"Reorganising",
69-
"Centralising"
69+
"Centralising",
70+
"Analyse",
71+
"Finalisation"
7072
,
7173
"gitlint"
7274
],

‎docs/plans/2026-02-01-repo-standards-gap-analysis.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Repo Standards Gap Analysis (Skills-Triggered)
2+
3+
> Status: In Progress
4+
> Owner: Codex
5+
> Date: 2026-02-01
6+
7+
## Goal
8+
9+
Analyse the current repository state against the standards implied by skills that would have triggered naturally during repo population, and document gaps with evidence.
10+
11+
## Architecture
12+
13+
Documentation-only change. No runtime or behavioural code changes.
14+
15+
## Tech Stack
16+
17+
- PowerShell
18+
- ripgrep (`rg`)
19+
- Markdownlint CLI2, CSpell (via `npm run verify`)
20+
21+
## Assumptions
22+
23+
- en-GB spelling is configured for CSpell.
24+
- Only skills in `skills/**/SKILL.md` are considered, using front matter and `When to Use` to determine trigger relevance.
25+
- The report will live in `docs/reports/2026-02-01-repo-standards-gap-analysis.md`.
26+
27+
## Alternatives Considered
28+
29+
1. Full manual audit against skills triggers (selected) for accuracy and evidence quality.
30+
2. Automated extraction + manual validation (faster, but more tooling overhead).
31+
3. Sampling-based review (fastest, weakest evidence).
32+
33+
## Task Checklist
34+
35+
|ID|Task|Status|Verification|Evidence|
36+
|---|---|---|---|---|
37+
|1|Impact analysis (RED/GREEN/REFACTOR): inventory skills, identify which would have triggered during repo population, and list impacted/unimpacted areas in the report header.|Done|Report scope notes include impacted/unimpacted set|`docs/reports/2026-02-01-repo-standards-gap-analysis.md`|
38+
|2|Report scaffold (RED/GREEN/REFACTOR): create the report with summary + per-skill table template (trigger rationale, required standards, repo evidence, gap status).|Done|Report file exists with headers and table template|`docs/reports/2026-02-01-repo-standards-gap-analysis.md`|
39+
|3|Trigger review (RED/GREEN/REFACTOR): read front matter + `When to Use` for each skill to decide if it would trigger for repo population; record rationale in the report.|Done|All relevant skills marked with trigger rationale|`docs/reports/2026-02-01-repo-standards-gap-analysis.md`|
40+
|4|Standards gap analysis (RED/GREEN/REFACTOR): for each triggered skill, compare required standards against repo state (configs, docs, CI, hooks) and capture evidence + gaps.|Done|Table populated with evidence and gap status|`docs/reports/2026-02-01-repo-standards-gap-analysis.md`|
41+
|5|Findings and recommendations (RED/GREEN/REFACTOR): summarise top gaps, recurring issues, and priority fixes with references to evidence.|Done|Summary section completed|`docs/reports/2026-02-01-repo-standards-gap-analysis.md`|
42+
|6|Verification + commit (RED/GREEN/REFACTOR): run `npm run verify`; fix lint/spell issues; commit on feature branch with a conventional commit (no commits to `main`).|Done|`npm run verify` clean|`npm run verify` passed after adding en-GB words to `cspell.json`.|
43+
44+
Notes:
45+
46+
- Status values: Planned, In Progress, Done, Aborted.
47+
- When a task is Done, fill in Verification and Evidence (command output, link, or note).
48+
49+
## Progress Log
50+
51+
- 2026-02-01: Draft plan created for repo standards gap analysis.
52+
- 2026-02-01: Impact scope documented and report scaffold created.
53+
- 2026-02-01: Trigger review completed and recorded in the report.
54+
- 2026-02-01: Standards gap analysis and findings recorded in the report.
55+
- 2026-02-01: Verification complete; `npm run verify` clean.
56+
57+
## Finalisation
58+
59+
> Outcome: Delivered | Aborted | Pending
60+
> Date: 2026-02-01
61+
62+
### Verification Summary
63+
64+
-
65+
66+
### References
67+
68+
- `AGENTS.md`
69+
- `skills/using-skill-library/SKILL.md`
70+
- `skills/writing-plans/SKILL.md`
71+
- `skills/documentation-as-code/SKILL.md`
72+
- `skills/incremental-change-impact/SKILL.md`
73+
- `skills/using-git-worktrees/SKILL.md`

‎docs/reports/2026-02-01-repo-standards-gap-analysis.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Repo Standards Gap Analysis
2+
3+
Date: 2026-02-01
4+
Owner: Codex
5+
6+
## Scope and Impact
7+
8+
Impacted (planned changes): `docs/reports/2026-02-01-repo-standards-gap-analysis.md`, `docs/plans/2026-02-01-repo-standards-gap-analysis.md`.
9+
Reviewed (no changes): repo configuration, CI/CD workflows, hooks, docs, and `skills/**/SKILL.md` for trigger decisions.
10+
Unimpacted: runtime code and deployable components (no application code changes).
11+
12+
## Summary
13+
14+
- 15 skills would have triggered during repo population based on front matter and `When to Use`.
15+
- Most repo standards are enforced via hooks and CI for documentation quality and commit conventions.
16+
- Key gaps: no automated guardrail to block commits on `main`, no CI enforcement for secret scanning, and limited CI/CD traceability controls (no tag-based release/deploy pipelines).
17+
18+
## Findings and Recommendations
19+
20+
- Add a `pre-commit` or `pre-push` guardrail to block commits or pushes to `main`, and document required branch protection settings (status checks, no direct pushes, no merge commits).
21+
- Add a CI job for `npm run secretlint` to make security scanning reproducible and enforceable.
22+
- Document CI/CD scope exceptions explicitly (no release/deploy pipelines) or add tag-based release/deploy workflows if required by operating context.
23+
24+
## Triggered Skills and Gaps
25+
26+
| Skill | Trigger rationale (from front matter + When to Use) | Required standards | Repo evidence | Gap status | Notes |
27+
| --- | --- | --- | --- | --- | --- |
28+
| repository-foundation-bootstrap | Bootstrapping a new repository or migrating a repo to this library's standards. | Baseline documented, brownfield path planned, ADRs for tooling/structure, zero-warning verification. | `docs/plans/2026-01-02-brownfield-standards-migration.md`, `docs/reports/2026-01-02-brownfield-impact.md`, `docs/adr/006-commit-message-validation-and-secret-scanning.md`, `npm run verify` in `README.md`. | Pass | Baseline and migration evidence are present. |
29+
| documentation-scaffold | Starting a new repository or migrating a repo missing/inconsistent docs. | `AGENTS.md` present, README setup/verification, ADRs for decisions, doc checks pass. | `AGENTS.md`, `README.md` (Development/Contributing), `docs/adr/*.md`, `npm run verify` in `README.md`. | Pass | Meets minimum doc scaffold expectations. |
30+
| documentation-as-code | Creating/updating README, plans, ADRs, or SKILL docs. | Linting and spell checks enforced, docs treated as code with CI gate. | `.markdownlint-cli2.yaml`, `.markdownlint.json`, `cspell.json`, `package.json` scripts, `.github/workflows/docs-quality.yml`, `.husky/pre-commit`. | Pass | Automated checks are in place for docs. |
31+
| writing-skills | Creating or modifying any `SKILL.md` during repo population. | Use skill template and enforce front matter constraints. | `skills/writing-skills/templates/skill_template.md`, `README.md` Contributing section. | Pass | Template and guidance exist; enforcement is manual. |
32+
| writing-plans | Producing multi-step plans in `docs/plans/`. | Plan template used and stored in `docs/plans/`. | `skills/writing-plans/templates/plan_template.md`, `docs/plans/2026-01-02-brownfield-standards-migration.md`. | Pass | Plans follow template and are stored in repo. |
33+
| incremental-change-impact | Any change set (docs/config/tooling) during repo setup. | Impact analysis documented with impacted/unimpacted set. | `docs/reports/2026-01-02-brownfield-impact.md`. | Pass | Explicit impact report exists. |
34+
| automated-standards-enforcement | Establishing tooling, linting, and quality gates for standards. | Prefer automated enforcement via hooks/CI over manual review. | `.husky/pre-commit`, `.husky/commit-msg`, `package.json` lint-staged config, `.github/workflows/docs-quality.yml`, `.github/workflows/commitlint.yml`. | Pass | Automated gates exist for docs and commits. |
35+
| local-dev-experience | Introducing hooks, linting, formatting, and staged-only checks. | Husky + lint-staged for staged-only checks; local verification commands. | `.husky/pre-commit`, `package.json` lint-staged config, `npm run verify` in `README.md`. | Pass | Staged-only hooks and local verify are configured. |
36+
| runtime-tooling-validation | Introducing/validating Node/tooling versions and policy. | LTS version pinned and enforced. | `.nvmrc`, `package.json` engines, `volta` node pin. | Pass | Runtime policy is explicit and consistent. |
37+
| static-analysis-security | Introducing or modifying security linting (e.g., secret scanning). | Security scans run and are reproducible; evidence recorded. | `.secretlintrc.json`, `.secretlintignore`, `package.json` `secretlint` script, lint-staged `secretlint`. | Gap | No CI job runs `secretlint`; enforcement is local only. |
38+
| ci-cd-conformance | Creating/modifying CI workflows to meet monorepo standards. | Incremental execution, quality gates, immutable releases, tag-based deployments. | `.github/workflows/docs-quality.yml` uses path filters; `commitlint.yml` enforces commit conventions. | Partial | Quality gates exist; no release/deploy pipelines or tag-based deployment evidence (scope may be N/A). |
39+
| branching-strategy-and-conventions | Defining branching strategy and commit conventions. | No direct commits to `main`, commitlint enforced, branch protection, pre-commit guardrail for default branch. | `.husky/commit-msg`, `.github/workflows/commitlint.yml`, `README.md` branch protection note. | Gap | No automated guardrail to block commits on `main`; branch protection enforcement not verifiable in repo. |
40+
| quality-gate-enforcement | Ensuring checks run and block before merge/tag/deploy. | Required checks block merges and releases with zero warnings. | `.github/workflows/docs-quality.yml`, `.github/workflows/commitlint.yml`, `npm run verify`. | Partial | Secret scanning not enforced in CI; quality gates limited to docs/commit linting. |
41+
| best-practice-introduction | Introducing new standards/tooling with safe rollout. | Incremental rollout plan and ADRs for tooling decisions. | `docs/plans/2026-01-02-brownfield-standards-migration.md`, `docs/adr/006-commit-message-validation-and-secret-scanning.md`. | Pass | Rollout plan and ADRs exist. |
42+
| using-git-worktrees | Multi-step work or need for isolation during repo setup. | Worktree location is defined and ignored; usage documented. | `.gitignore` includes `.worktrees/`, `AGENTS.md` step 5. | Pass | Worktree policy is documented and supported. |

0 commit comments

Comments
 (0)