Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 7 additions & 10 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,22 @@

## CQA Compliance

When editing `.adoc` files, ALWAYS run the relevant CQA scripts to validate and fix changes before considering the task done. Run all 19 checks at once with `build/scripts/cqa.sh`, or run individual scripts. All share a common interface via `build/scripts/cqa-lib.sh`:
When editing `.adoc` files, ALWAYS run the relevant CQA checks to validate and fix changes before considering the task done:

```bash
# Report issues for a title
./build/scripts/cqa.sh titles/<title>/master.adoc
node build/scripts/cqa/index.js titles/<title>/master.adoc

# Auto-fix issues
./build/scripts/cqa.sh --fix titles/<title>/master.adoc
node build/scripts/cqa/index.js --fix titles/<title>/master.adoc

# Run across all titles
./build/scripts/cqa.sh --all

# Auto-fix across all titles
./build/scripts/cqa.sh --fix --all
# Run a single check
node build/scripts/cqa/index.js --check NN titles/<title>/master.adoc
```

Output markers: `[AUTOFIX]` (auto-fixable), `[FIXED]` (applied), `[MANUAL]` (needs human), `[-> CQA-NN AUTOFIX]` / `[-> CQA-NN MANUAL]` (delegated).

For full CQA workflow, load `.claude/skills/cqa-main-workflow.md`. Individual skill files are in `.claude/skills/cqa-*.md`.
The `project-cqa` plugin (`.claude/plugins/project-cqa/`) provides skills for the full CQA workflow and individual checks. The CQA spec is at `.claude/plugins/project-cqa/resources/cqa-spec.md`.

## Pull Requests

Expand All @@ -35,7 +32,7 @@ When creating PRs, follow `.github/pull_request_template.md`:

| Workflow | Trigger | Purpose |
|---|---|---|
| `content-quality-assessment.yml` | PR (`.adoc`, `build/scripts/`) | Runs `cqa.sh --all` on entire repo. Posts checklist as PR comment, uploads SARIF to Code Scanning. Scripts sourced from `main` branch (not base) for backport compatibility. |
| `content-quality-assessment.yml` | PR (`.adoc`, `build/scripts/`) | Runs `node build/scripts/cqa/index.js --all` on entire repo. Posts checklist as PR comment. Scripts sourced from `main` branch (not base) for backport compatibility. |
| `build-asciidoc.yml` | Push to main/release | Builds AsciiDoc docs and deploys to GitHub Pages. Cleans up merged PR preview branches. |
| `pr.yml` | PR | Builds HTML preview, deploys to `gh-pages`, posts preview URL as PR comment. |
| `style-guide.yml` | PR | Runs Vale linter on `assemblies/` for style guide compliance. |
Expand Down
56 changes: 10 additions & 46 deletions .claude/MEMORY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,55 +2,19 @@

This file contains persistent knowledge about working with the RHDH documentation repository for Claude Code.

## CQA 2.1 Compliance Process
## CQA 2.1 Compliance

**ALWAYS use the checklist for CQA work:**
The `project-cqa` plugin (`.claude/plugins/project-cqa/`) provides:
- **Skills:** `cqa-main-workflow` orchestrates all 19 checks; individual `cqa-NN-*` skills for each check
- **Spec:** `resources/cqa-spec.md` is the single source of truth for all check logic
- **Resources:** Style guides, templates, and reference materials

1. **FIRST:** Load the workflow files
```
Read .claude/skills/cqa-main-workflow.md, .claude/cqa-checklist.md, .claude/MEMORY.md
```
- The main workflow orchestrates all 17 CQA requirements in optimal order
- The checklist follows the same 5-phase structure
- **Idempotency requirement:** Re-execute each requirement until no changes, then re-run entire workflow until stable
**Script interface:**
```bash
node build/scripts/cqa/index.js [--fix] [--check NN] titles/<title>/master.adoc
```

2. **VERIFY required information** - If any are missing, ASK the user:
- JIRA ticket number (e.g., RHIDP-12345)
- Title name or path to master.adoc file

3. **THEN:** Use the master workflow as the guide
- Create a TodoWrite following the sequence in cqa-main-workflow.md
- Read individual CQA skills (.claude/skills/cqa-##-*.md) for detailed assessment
- Run each step sequentially; respect the sequence order

4. **NEVER claim completion unless:**
- ALL checkbox items are marked with a checkmark
- Idempotency verified (re-running workflow produces no changes)
- TodoWrite shows all tasks complete

### Reference Materials

Updated using `./build/scripts/update-cqa-resources.sh` (weekly minimum, daily maximum).
See `.claude/skills/update-all-resources.md` for details.

- **SSG:** `.claude/resources/red-hat-ssg.md` — grammar, style, formatting (CQA 8, 9, 10, 12, 16)
- **Peer Review:** `.claude/resources/red-hat-peer-review.md` — titles, grammar, editorial quality (CQA 10, 12)
- **Modular Docs:** `.claude/resources/red-hat-modular-docs.md` — content types, module templates (CQA 2-6, 10, 13)
- **Vale:** `.vale-dita-only.ini` (CQA 1), `.vale.ini` (CQA 12). Sync with `vale sync`. `attributes.adoc` excluded from Vale.

### Best Practices

1. **Scripts first, manual second:** Run all automated scripts before manual fixes
2. **One step at a time:** Don't batch steps, even if they seem related
3. **Verify after fixes:** Re-run scripts after manual changes to confirm alignment
4. **Git mv for renames:** Always use git mv to preserve history
5. **Idempotency:** Re-run each CQA requirement until no changes, then re-run full workflow until stable

### Pull Request Guidelines

**Never use `#` notation for CQA numbers** in PR descriptions (e.g., write "CQA 1" not "CQA-1"). GitHub auto-links `#number` to unrelated issues/PRs.

PR description format is in `.claude/cqa-checklist.md`.
**Never use `#` notation for CQA numbers** in PR descriptions — GitHub auto-links `#number`.

## Repository Structure

Expand Down
Loading
Loading