diff --git a/.claude/skills/proof-spec/SKILL.md b/.claude/skills/proof-spec/SKILL.md new file mode 100644 index 0000000000..3d700fdd8c --- /dev/null +++ b/.claude/skills/proof-spec/SKILL.md @@ -0,0 +1,227 @@ +--- +name: proof-spec +description: Proof BIDS specification documents for language, grammar, markdown formatting, macro syntax, content rendering, and build verification. Use this skill to comprehensively check specification documents before submitting pull requests. +--- + +# Proof BIDS Specification + +You are a specialized proofreading agent for the BIDS (Brain Imaging Data Structure) specification documents. + +## Task Overview + +Proof the BIDS specification by checking: +1. Language, grammar, and typos +2. Proper rendering of content (images, tables, file trees) +3. Macro syntax and functionality +4. Markdown formatting compliance with style guide +5. Link integrity +6. YAML schema validity + +## Repository Structure + +- **Documentation source**: `src/` directory contains markdown files +- **YAML schema**: `src/schema/` directory +- **Macros**: `tools/mkdocs_macros_bids/macros.py` defines macros called via `{{ MACROS___macro_name() }}` +- **Build command**: `mkdocs serve` to build and serve locally +- **Markdown checker**: `npx remark --frail` to check style + +## Available Macros + +The following macros are used in the specification: +- `MACROS___make_filename_template` - Generates filename templates from schema +- `MACROS___make_entity_table` - Creates entity tables +- `MACROS___make_entity_definitions` - Generates entity definitions +- `MACROS___make_glossary` - Creates glossary +- `MACROS___make_suffix_table` - Creates suffix tables +- `MACROS___make_metadata_table` - Creates metadata tables +- `MACROS___make_json_table` - Creates JSON tables +- `MACROS___make_sidecar_table` - Creates sidecar tables +- `MACROS___make_subobject_table` - Creates subobject tables +- `MACROS___make_columns_table` - Creates columns tables +- `MACROS___make_filetree_example` - Generates file tree examples +- `MACROS___define_common_principles` - Defines common principles +- `MACROS___define_allowed_top_directories` - Defines allowed directories +- `MACROS___render_text` - Renders text from schema + +## Custom Fences + +TSV tables are rendered using special code fences: +- ` ```tsv` - Renders tab-separated values as table +- ` ```tsvgz` - Renders tab-separated values without header + +## Proofing Steps + +When proofing a file or the entire specification: + +### 1. Language and Grammar Check + +- Check for typos and spelling errors +- Verify American English is used (not British English) +- Check for proper grammar and sentence structure +- Verify technical terminology is used consistently +- Look for Latin abbreviations (e.g., i.e., etc.) which should be avoided +- Check that each sentence starts on a new line (per style guide) + +### 2. Markdown Formatting + +- Verify compliance with the Markdown Style Guide +- Check proper use of headers (hierarchy) +- Verify code blocks use proper syntax highlighting +- Check that lists are properly formatted +- Verify links use proper markdown syntax +- Check that hard word wrapping is appropriate (80-100 chars) +- Verify images have alt text + +### 3. Macro Syntax + +- Check that macros are called with proper syntax: `{{ MACROS___macro_name() }}` +- Verify macro calls are not malformed +- Check that macro names are spelled correctly +- Verify macros are called with appropriate parameters when needed + +### 4. Content Rendering + +**Images:** +- Verify image paths are correct relative to the document +- Check that images exist in the repository +- Verify alt text is provided +- Check image references in markdown are properly formatted + +**Tables:** +- Verify TSV code fences render properly (check tab separation) +- Check that table headers are appropriate +- Verify table content aligns properly +- Check for any malformed tables + +**File Trees:** +- Verify file tree examples are properly formatted +- Check that file tree macros are called correctly +- Verify indentation is consistent + +### 5. Links + +- Check internal links point to valid files/sections +- Verify external links are properly formatted +- Check for broken anchor links +- Verify relative paths are correct + +### 6. YAML Schema (if checking schema files) + +- Run `prettier --write "src/schema/**/*.yaml"` to check formatting +- Run `python -m yamllint -f standard src/schema/ -c .yamllint.yml` to lint +- Verify YAML syntax is valid +- Check indentation (2 spaces) +- Check line length (120 chars max) + +### 7. Build Verification + +- Build the specification with `mkdocs serve` to verify no errors +- Check for any warnings or errors in the build output +- Verify that macros expand correctly +- Check that the rendered HTML looks correct + +## Workflow + +When asked to proof the specification: + +1. **Determine scope**: Ask user which files to proof (single file, directory, or entire spec) + +2. **Run markdown checks**: Use `npx remark --frail` on markdown files + +3. **Check language and content**: Read through files looking for issues + +4. **Verify macros and rendering**: + - Check macro syntax in markdown + - Optionally build with mkdocs to verify rendering + +5. **Check links and images**: + - Verify image paths + - Check internal links + +6. **Report findings**: Provide a clear summary of issues found, organized by category + +7. **Fix issues (if requested)**: Make corrections using the Edit tool + +## Style Guidelines + +**Language:** +- Use American English +- Avoid Latin abbreviations (i.e., e.g., etc.) +- Use "for example" instead of "e.g." +- Use "that is" instead of "i.e." +- Use proper technical terminology + +**Markdown:** +- One sentence per line +- Hard wrap at 80-100 characters +- Use proper header hierarchy +- Use fenced code blocks with language identifiers +- Include alt text for images +- Use relative links where appropriate + +**JSON Examples:** +- Always use double quotes around string values +- Properly format and indent JSON + +## Example Commands + +```bash +# Check a specific markdown file +npx remark src/common-principles.md --frail + +# Check multiple files +npx remark ./src/*.md ./src/*/*.md + +# Build and serve to check rendering +mkdocs serve + +# Format YAML schema +prettier --write "src/schema/**/*.yaml" + +# Lint YAML +python -m yamllint -f standard src/schema/ -c .yamllint.yml + +# Run schema tests +pytest tools/schemacode/ +``` + +## Output Format + +When reporting issues, use this format: + +``` +## Proofing Results for [file/section] + +### Language and Grammar +- [Issue 1]: filename:line X - description +- [Issue 2]: filename:line Y - description + +### Markdown Formatting +- [Issue]: filename:line X - description + +### Macros +- [Issue]: filename:line X - description + +### Images/Tables/Content +- [Issue]: filename - description + +### Links +- [Issue]: filename - description + +### Build Errors +- [Error]: description + +## Summary +- Total issues found: N +- Critical issues: N (prevent building) +- Style issues: N +- Language issues: N +``` + +## Important Notes + +- Always verify changes don't break the mkdocs build +- Be careful when modifying macro calls +- Preserve exact indentation in YAML schema files +- Don't modify technical terms or schema-generated content +- When in doubt about a language correction, explain the rationale diff --git a/.gitignore b/.gitignore index 3fd3490188..24b049177c 100644 --- a/.gitignore +++ b/.gitignore @@ -161,3 +161,6 @@ dmypy.json cython_debug/ .*.swp + +# Claude code local config +.claude/settings.local.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97c5e9515c..194a00d9a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -342,6 +342,58 @@ Using `remark` to fix some linting errors might introduce some additional change You might have to revert those or use [interactive staging](https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging) to make sure you only commit the right chunks of code. +## Proofing the specification with Claude Code + +If you have access to [Claude Code](https://claude.ai/code), you can use the `proof-spec` skill +to comprehensively check specification documents for issues before submitting a pull request. + +### What the proofing skill checks + +The proofing skill (`.claude/skills/proof-spec/SKILL.md`) performs comprehensive quality checks on +specification documents, including: + +- **Language and grammar**: Detects typos, duplicated words, incorrect word usage, and punctuation issues +- **American English compliance**: Ensures American English spelling and absence of Latin abbreviations (e.g., i.e., etc.) +- **Markdown formatting**: Validates compliance with the Markdown Style Guide (same checks as `remark`) +- **Macro syntax**: Verifies correct usage of mkdocs macros (for example, `{{ MACROS___make_entity_table() }}`) +- **Content rendering**: Checks proper formatting of images, tables, file trees, and TSV fences +- **Link integrity**: Validates internal and external links +- **Build verification**: Optionally tests that the specification builds without errors + +### How to use the proofing skill + +To proof a specific file using Claude Code: + +```bash +claude-code +``` + +Then ask Claude to proof a file: + +``` +Please proof src/common-principles.md using the proof-spec skill +``` + +Or to proof multiple files: + +``` +Please proof all markdown files in src/modality-specific-files/ using the proof-spec skill +``` + +The skill will provide a detailed report of issues organized by category (language, formatting, macros, etc.) +and can optionally fix the issues it finds. + +### When to use the proofing skill + +- Before submitting a pull request with documentation changes +- After making substantial edits to specification documents +- When reviewing pull requests +- Periodically to catch accumulated issues in the specification + +The proofing skill complements the automated `remark` checks and can catch issues that +automated linters might miss, such as duplicated words, incorrect terminology, or +rendering problems with macros and custom fences. + ## Adding a figure to the specifications > A figure is worth a 1000 words!