Skip to content

Remove stale design-spec references and fix doc-gen wording - #26

Merged
jeffhorn-nava merged 2 commits into
mainfrom
jeffhorn/2-remove-stale-spec-references
Jul 9, 2026
Merged

Remove stale design-spec references and fix doc-gen wording#26
jeffhorn-nava merged 2 commits into
mainfrom
jeffhorn/2-remove-stale-spec-references

Conversation

@jeffhorn-nava

Copy link
Copy Markdown
Collaborator

What

Removes references to a docs/superpowers/ design spec that was never committed, and corrects README's description of when the doc-generation Actions run. The pipeline and skills are themselves the source of truth now, so the historical spec does not need to live in the repo.

Closes #2

How

Dropped all six sites that pointed at the spec: the docs/superpowers/ links in README.md, AGENTS.md, and rules/architecture.md, and the §-section annotations (§3.3, §3.3b, §3.6, §8) in scripts/lint_docs.py, skills/generate-strata-docs/SKILL.md, and skills/generate-strata-docs/references/agents/source-doc.md. Load-bearing phrasing next to an annotation (e.g. "no fallback" beside §8) was preserved. Also changed README's "manual, weekly, or on sources.md change" to "manual", matching the workflow_dispatch-only triggers and AGENTS.

Test plan

  • python -m scripts.lint_manifest → MANIFEST_OK (9 sources)
  • python -m scripts.lint_docs → DOCS_OK (56 docs)
  • python -m scripts.build_graph → GRAPH_OK; no change to docs/INDEX.md or docs/graph.json
  • python -m pytest -q → 53 passed
  • grep confirms no docs/superpowers or spec § references remain

Notes for reviewers

Docs, skill instructions, and code comments only; no build or runtime impact. The FMLA legal citations (§ 2612, § 825) in docs/sources/ and docs/.verification/ are unrelated to the design spec and were left in place.

README, AGENTS, the architecture rule, the linter, and the
generate-strata-docs skill pointed at a docs/superpowers/ design
spec and its section numbers (§3.3, §3.3b, §3.6, §8). That spec was
never committed; the running pipeline and skills are the source of
truth, so remove the references instead of resurrecting it.

README also claimed the doc-generation Action runs "weekly, or on
sources.md change". Both doc actions are workflow_dispatch only, so
they run manually; AGENTS already described this correctly.

Closes #2
@jeffhorn-nava

Copy link
Copy Markdown
Collaborator Author

Adjacent correction to fold in: stale trigger comment in generate-docs.yml

While reviewing this PR (which correctly narrows the README trigger wording to "manual"), I found one more spot with the same class of stale claim, just outside this diff. Flagging it here so it can be picked up separately.

File: .github/workflows/generate-docs.yml, line 3

Current:

# Routine drift refresh + new-source pickup lives in update-docs.yml (cron + manual).

Problem: update-docs.yml is on: workflow_dispatch: only — there is no schedule/cron trigger. The "(cron + manual)" parenthetical contradicts both the actual workflow definition and rules/ci.md:15, which already states both workflows are "manual only."

Suggested fix: drop the cron + , e.g.

# Routine drift refresh + new-source pickup lives in update-docs.yml (manual dispatch).

Not introduced by this PR, so leaving it out of scope is fine. Noting it because it's the same "when do the doc-gen Actions run" accuracy fix this PR makes, in the place a maintainer is most likely to read it.

update-docs.yml is workflow_dispatch only; the (cron + manual) note
contradicted the workflow definition and rules/ci.md.
@jeffhorn-nava
jeffhorn-nava marked this pull request as ready for review July 8, 2026 21:45
@jeffhorn-nava
jeffhorn-nava merged commit 7ce73d6 into main Jul 9, 2026
1 check passed
@jeffhorn-nava
jeffhorn-nava deleted the jeffhorn/2-remove-stale-spec-references branch July 9, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix stale doc references to the design spec and doc-regeneration wording

2 participants