docopslab-dev 0.1.0

data/docs/agent/skills/code-commenting.md

@@ -0,0 +1,347 @@
+# Code Commenting
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+Employing good code commenting practices is more important than ever in the age of LLM-assisted programming. Existing comments are a model for future comments, and poor commenting hygiene is contagious.
+
+In order to maximize the usefulness of code comments for both human and AI readers, DocOps Lab projects follow specific commenting conventions, including purpose and style constraints.
+
+LLM-backed tools and linters are used to review comments and enforce adherence to these conventions, but developer attention is critical. Comments are unlikely to be improved upon after initially merged.
+
+Table of Contents
+
+- Code Comments Orientation
+- Kinds of Comments
+      - Flavors of Code
+      - General Style Rules
+- Expository Comments: Use and Abuse
+- Principles
+      - General Examples
+      - Style
+      - Examples
+- Comment Protocols by Language
+- Ruby Commenting Protocols
+      - YAML Commenting Protocols
+
+## Code Comments Orientation
+
+To begin, we will standardize our understanding of what types of comments are applied to what kinds of code.
+
+### Kinds of Comments
+
+Code comments come in several distinct types.
+
+**documentation** :
+   Code comments used to build downstream-facing reference docs for methods, classes, functions, data objects, and so forth.
+
+   _Docstrings_ are specifically comments used in the generation of rich-text reference docs. That they also happen to “document” the code to which they are adjacent is secondary.
+
+**expository** :
+   Code comments that explain the purpose or function of code blocks, algorithms, or complex logic, strictly in natural language. Also called “inline comments”, these arbitrary remarks are mainly what is governed by this protocol guide.
+
+**rationale** :
+   Comments that explain the reasoning behind a particular implementation choice, design pattern, or data structure.
+
+**status** :
+   Stability and lifecycle markers: `DEPRECATED:`, `EXPERIMENTAL:`, `INTERNAL:`, `UNSTABLE:`. May also include planned removal dates, version gates, feature flags.
+
+**admonition** :
+   Developer-facing warnings, notes, or tips embedded in code. Use `WARNING:`, `NOTE:`, and `TIP:` prefixes to mark these comments distinctly.
+
+**task** :
+   Comments like `TODO:` and `FIXME:` are used to mark code that needs further work.
+
+**instructional** :
+   Code comments left in template, stub, or sample files for interactive use. These comments tend to be intended for a downstream user who will interact directly with the file or one based on it.
+
+**label** :
+   Comments that simply annotate sections of code by category or general purpose, to help with demarcation and navigation. These comments are usually brief and may use special formatting to stand out.
+
+**directive** :
+   In some languages, we use special character patterns to signify that a comment has a special purpose, other than for generating reference docs. These comments may mark code for special parsing, content transclusion, or other operations.
+
+   In AsciiDoc, comments like `// tag::example[]` and `// end::example[]` are used to mark content for inclusion elsewhere.
+
+   The popular linter Vale recognizes HTML comments like `<!-- vale off -→` and `<!-- vale on -→` to disable and re-enable content linting.
+
+**sequential/collection** :
+   Comments that number or order logical stages in a complex or lengthy process or members of a set. Usually something like `# STEP 1:`, `# PHASE 1:`, and so forth, or else `# GROUP A:`, `# SECTION 1:`, etc. Always use uppercase for these markers (ex: `# STEP:` not `# Step:`).
+
+### Flavors of Code
+
+**Ruby** :
+   The most robust environment for code comments, Ruby supports RDoc/YARD-style documentation comments that can be used to generate reference documentation. See Ruby Commenting Protocols for more.
+
+**Bash** :
+   We make extensive use of comments in Bash scripts, but Bash has no standard for documentation comments or structured comments.
+
+**AsciiDoc** :
+   Comments in `.adoc` files tend to be labels, tasks, and directives (AsciiDoc tags). AsciiDoc files tend not to have expository comments, since the content is already documentation.
+
+**YAML/SGYML** :
+   YAML files use copious label and instructional comments to help downstream users navigate and understand large or complex data structures. Comments can also be used to annotate nesting depth. See YAML Commenting Protocols for more.
+
+**Liquid** :
+   Our use of Liquid comments is inconsistent at best. Part of the problem is their terrible format with explicit `{% comment %}` and `{% endcomment %}` tags. While Liquid 5 has greatly improved that, DocOps Lab tooling is standardized on Liquid 4 at this time.
+
+**HTML** :
+   We don’t code much HTML directly. It is mostly either converted from lightweight markup or rendered by Liquid templates (or JavaScript). Comments are usually to mark nested objects for convenience, to label major structures or to highlight/clarify obscure asset references, or as directives such as `<!-- vale off -→`, which disables content linting.
+
+**JavaScript** :
+   We are not a JavaScript shop, but we do write a good bit of vanilla JavaScript. Comments are used mainly to establish our bearings in the code and therefor are sometimes heavier than with other languages.
+
+**CSS/SCSS** :
+   We mainly write CSS as SCSS, and commenting is mainly to express the intent upon compiling.
+
+### General Style Rules
+
+- Do not use em dashes or en dashes or (` - `).
+
+   - Use colons (`: `) to prefix a comment with a classification.
+   - Use semicolons (`; `) to break up clauses.
+- Use sentence-style capitalization.
+- Do not use terminal punctuation (periods, exclamation points, question marks) unless the comment is multiple sentences.
+- Hard wrap comments around 110-120 characters.
+
+   - Use one-sentence per line.
+   - Try not to wrap anything _except_ full sentences.
+   - When wrapping multi-line sentences, indent subsequent lines by an additional space.
+
+## Expository Comments: Use and Abuse
+
+Arbitrary inline comments used to explain code should be used consistently and only when they add value.
+
+Arbitrary comments can _often_ add value, under an array of conditions that may be more art than science. We must be forgiving and understanding of occasional or even frequent misfires in various developers' subjective takes on what is useful.
+
+This guide exists to help with comment evaluation.
+
+### Principles
+
+Expository comments (and their authors) should adhere to these principles:
+
+**1) Express purpose, not implementation.**:
+   Comments should explain why code exists or what it is intended to do, rather than how it does it. (Rationale comments are available for explaining design/engineering choices, if necessary.)
+
+**2) Summarize peculiar or complex implementation (without violating #1).**:
+   Expository comments may _include_ a _brief_ reference to an explicit design choice. Still not a _rationale comment_ (too brief, in passing) nor a _task comment_ (no further action prescribed), just a nod to an unusual or non-obvious implementation detail.
+
+**3) Use natural, imperative language.**:
+   Comments should not contain code, and they should be formatted as English clauses or sentences. Comments should be phrased as commands or instructions, focusing on the action being performed, from the perspective of what the code is to do.
+
+**4) Be concise.**:
+   Comments should be as brief as possible. Multi-sentence comments should be the exception. In fact, comments should not typically be complete sentences.
+
+**5) Maintain relevance and accuracy.**:
+   Comments should be reviewed and updated as code changes to ensure they remain accurate and relevant.
+
+**6) Never cover straightforward code (except…​).**:
+   Not all blocks need comments at all. The main criterion is whether the code’s purpose or function would not be _immediately_ clear from the code itself to a newcomer with beginner or intermediate knowledge of the language and little familiarity with the application architecture.
+
+   Exception: Sometimes an oddity or pivotal point needs to be highlighted even in otherwise straightforward code.
+
+**7} Do not use comments as notes to reviewers.** :
+   Temporary comments intended to guide code reviewers should be avoided. Code used to help with flag logical points or communicate during pair programming or pre-commit review should be denoted as admonitions (such as `# LOGIC: ` or `# REVIEW: `) or `# TEMP: ` and removed before merging.
+
+### General Examples
+
+#### Unnecessary Comments
+
+```ruby
+# Create destination directory if needed
+FileUtils.mkdir_p(File.dirname(target_path))
+```
+
+This code does _exactly and only_ what the English comment says. In fact, the comment is muddier than the code. The code will create any necessary parent directories, whereas the comment only mentions the destination directory itself and does not explain _if needed_. In `mkdor_p`, the _if needed_ means _if the ancestor directories do not exist_.
+
+```ruby
+# Determine if we should copy the file
+file_existed_before_copy = File.exist?(target_path)
+```
+
+This comment is trying to explain the _purpose_ of the line it precedes, but this is unnecessary. The code itself merely sets a variable to a Boolean value. Not only is the direct purpose of the variable clear from its name and the code making up its value, but the purpose of the variable is only relevant in the context of later code that uses it.
+
+#### Comments that Add Value
+
+```ruby
+end
+
+# Public helper methods accessible to LogIssue class
+
+def normalize_source_path source_file
+  normalized = source_file.gsub(/#excerpt$/, '').gsub(%r{/$}, '')
+  normalized.gsub(%r{^\./}, '')
+end
+
+def normalize_problem_path reported_path, source_file
+```
+
+A comment preceded and followed by blank lines indicates that it references or labels multiple subsequent blocks. (Or it is be part of a series of such comments that tend to and in its own case may yet still cover multiple blocks each.)
+
+This categorizes sections for user convenience. It also helps LLM-backed tools to find relevant sections more easily.
+
+```ruby
+# Try to convert absolute path back to relative path
+if missing_path =~ %r{/home/[^/]+/[^/]+/work/[^/]+/(.+)$} ||
+    missing_path =~ %r{/([^/]+/[^/]+\.adoc)$}
+  @path = Regexp.last_match(1)
+end
+```
+
+Summarizing a complex Regex pattern is vital. Conveying the _intent_ of the pattern is far more important than explaining its mechanics.
+
+### Style
+
+Expository comments have a _subject_: the code they refer to, typically in the form of a line or block. In nearly all cases, comments should immediately precede the subject code.
+
+Example of comment preceding subject code
+
+```ruby
+# Validate all inputs individually
+inputs.each do |input|
+  # ...
+end
+```
+
+In some languages, comments can be placed inline. This should be used sparingly.
+
+We most commonly do this in YAML files.
+
+Example of inline comment in YAML
+
+```yaml
+inputs: # List of inputs to validate
+  - input1
+  - input2
+```
+
+We also do this in JavaScript files.
+
+Example of inline comment in JavaScript
+
+```javascript
+let count = calculated; // Start with the dynamic value
+```
+
+### Examples
+
+Good comment examples
+
+```ruby
+# Calculate the factorial of a number using recursion
+
+# Handle the base case
+
+# Never call factorial with a negative number
+
+# Validate all inputs individually
+```
+
+Good comments are descriptive and purely abstract. They express an instruction and/or a principle to be adhered to or enforced within the subject block.
+
+Bad comment examples (too simple/unnecessary)
+
+```ruby
+# Initialize the result to 1
+
+# Loop through numbers from 1 to n
+
+# Return the result
+```
+
+Bad comment examples (non-imperative form)
+
+```ruby
+# Calculates the factorial of a number
+```
+
+## Comment Protocols by Language
+
+### Ruby Commenting Protocols
+
+All public-facing methods and classes should be documented with YARD documentation comments.
+
+For expository comments, follow the Principles outlined above.
+
+#### API Documentation Comments
+
+Many of our Ruby gems provide public APIs that are documented using YARD.
+
+Private methods and classes may also be documented, but this is not required.
+
+Never describe a method just by what it returns or what parameters it takes. Describe what the method _does_ behind the scenes or what its summarized purpose.
+
+When documenting Ruby classes and methods with YARD, follow these patterns:
+
+**class descriptions** :
+   Keep class descriptions focused on the class’s primary responsibility and role within the system. Avoid overselling capabilities or implementation details.
+
+**method descriptions** :
+   Lead with what the method accomplishes, not just its signature. Example: "Processes the provided attributes to populate Change properties" rather than "Initializes a new Change object."
+
+**capitalization consistency** :
+   When referring to class objects conceptually or as an instance (not variable names), use CamelCase names. Use lowercase for most instances where the term refers to a real-world object or concept.
+
+**voice consistency** :
+   Use descriptive, present-tense “voice” for API documentation and YARD comments.
+
+#### Exceptions
+
+On rare occasions, comments are used to denote deep nesting in large files.
+
+Annotating `end` keywords that wrap up large blocks/statements
+
+```ruby
+end # method my_method
+      end # class MyClass
+    end # module MyModule
+  end # module SuperModule
+end # module OurCoolGem
+```
+
+Whenever possible, even when deep nesting is warranted, keep files small enough that such labels won’t be need, all else being equal.
+
+### YAML Commenting Protocols
+
+YAML files often contain extensive comments to help users understand the structure and purpose of the data.
+
+Comments should be used to label sections, explain complex structures, and provide hints or assistance for downstream/later users populating data fields.
+
+Examples of YAML comments
+
+```yaml
+# General data
+inputs:
+  - name: input1 # required
+  - name: input2 # optional
+config: # Settings for the application itself
+  setting1: value1 # Enable feature X (which is not called setting1 and thus needs translation)
+body: | # Use AsciiDoc format
+  This is content for the body of something.
+```
+
+We sometimes use comments to categorize a large Array or Map for navigation, even if the data is included in all members of the Array.
+
+Example of YAML section label
+
+```yaml
+# POSTS
+- slug: first-post
+  title: My First Post
+  type: post
+
+- slug: second-post
+  title: My Second Post
+  type: post
+
+# - etc
+
+# PAGES
+- slug: about
+  title: About Me
+  type: page
+
+# - etc
+```
+
+This is used when it makes no sense to nest data under parent keys like `posts:` and `pages:`, yet users will still need to navigate through large collections.
+

data/docs/agent/skills/fix-broken-links.md

@@ -0,0 +1,309 @@
+# Fix Broken Links
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+Original sources for this document include:
+
+<!-- detect the origin url based on the slug (origin) -->
+- [Fix Broken Links](/docs/agent/fix-broken-links/)
+
+A systematic approach to debugging and fixing broken links in DocOps Lab websites or sites generated with DocOps Lab tooling.
+
+Due to complex sourcing procedures at work in DocOps Lab projects, where a particular link comes from is not always obvious.
+
+This guide focuses on the methodologies for tracing link sources rather than specific solutions, making it applicable across different Jekyll/AsciiDoc sites.
+
+Table of Contents
+
+- Common Link Failure Patterns
+- External Link Failures
+      - Internal Link Failures
+- Debugging Methodology
+- Step 1: Run HTMLProofer and Categorize Failures
+      - Step 2: Identify High-Impact Patterns
+      - Step 3: Trace Link Sources
+      - Step 4: Apply Appropriate Fix Strategy
+- Data-Driven Link Debugging
+- YAML Data Sources
+      - Dependency Tracing Process
+      - Example Trace: AsciiDocsy Links
+- Pre-Publication Link Strategy
+- Validation and Testing
+- Rebuild and Verify
+      - Test Cycle
+- Prevention Strategies
+- Development Practices
+      - Configuration Management
+
+## Common Link Failure Patterns
+
+### External Link Failures
+
+**Network timeouts** :
+   Temporary connectivity issues that resolve after rebuild
+
+**404 errors** :
+   Missing pages or incorrect URLs
+
+**Pre-publication links** :
+   Links to repositories or resources not yet available
+
+**Malformed URLs** :
+   Missing repository names or incorrect paths
+
+### Internal Link Failures
+
+**Missing project anchors** :
+   Data/template mismatches in generated content
+
+**Section anchor mismatches** :
+   ID generation vs link target differences
+
+**Template variable errors** :
+   Unprocessed variables in URLs
+
+**Missing pages** :
+   Links to pages that don’t exist
+
+## Debugging Methodology
+
+### Step 1: Run HTMLProofer and Categorize Failures
+
+Run link validation
+
+```
+bundle exec rake labdev:lint:html 2>&1 | tee .agent/scratch/link-failures.txt
+```
+
+Extract external failure patterns
+
+```
+grep "External link.*failed" .agent/scratch/link-failures.txt | wc -l
+```
+
+Extract internal failure patterns
+
+```
+grep "internally linking" .agent/scratch/link-failures.txt | wc -l
+```
+
+### Step 2: Identify High-Impact Patterns
+
+Look for repeated failures across multiple pages:
+
+- Same broken link appearing on 3+ pages = template/data issue
+- Similar link patterns = systematic problem
+- Timeout clusters = network/rebuild issue
+
+### Step 3: Trace Link Sources
+
+#### For Missing Anchors (Internal Links and X-refs)
+
+If the problem is an anchor that does not exist, either the pointer or the anchor must be wrong.
+
+****Consider how the page was generated:**** :
+   - Is it a standard `.adoc` file?
+   - Is it a Liquid-rendered HTML page?
+   - Is it a Liquid-rendered AsciiDoc file (usually `*.adoc.liquid` or `*.asciidoc`)
+
+****For standard AsciiDoc files…​**** :
+   The offending link source will likely be:
+
+   1. an AsciiDoc xref (`<<anchor-slug>>` or `xref:anchor-slug[]`)
+   2. a pre-generated xref in the form of an attribute placeholder (`{xref_scope_anchor-slug_link}`) that has resolved to a proper AsciiDoc xref
+   3. a hybrid reference (`link:{xref_scope_anchor-slug_url}[some text]`)
+
+   In any case, the `anchor-slug` portion should correspond literally to the reported missing anchor. If these are rendering properly and do not contain obvious misspellings, consider how the intended target might be misspelled or missing and address the source of the anchor itself.
+
+****For Liquid-rendered pages…​**** :
+   The offending link source will likely be a misspelled or poorly constructed link.
+
+   1. a hard-coded link in Liquid/HTML (`"a href="#anchor-slug">`)
+   2. a data-driven link in Liquid/HTML (`"a href="#{{ variable | slugify }}">`)
+   3. a data-driven link in Liquid/AsciiDoc (`link:#{{ variable | slugify }}`)
+   4. a pre-generated xref in the form of an attribute placeholder (`{xref_some-scope_some-slug-string_link}`; generated from Liquid such as: `{xref_{{ scope }}_{{ variable }}_link}`)
+
+   Other than for hard-coded links, you will need to trace the source to one of the following:
+
+   - A YAML file, typically in a `_data/` or `data/` directory.
+
+   Search for the offending anchor
+
+   ```
+   grep -rn "broken-anchor-slug" --include \*.yml --include \*.yaml
+   ```
+
+   > **NOTE:** If there are numerous errors of this kind, the problem _could_ be in the code that generates the attributes from the YAML source.
+   - Attributes derived from a file like `README.adoc`.
+
+   Search for the offending attribute
+
+   ```
+   grep -rn "^:.*broken-anchor.*:" --include \*.adoc
+   ```
+
+****Other tips for investigating broken anchors:**** :
+   Check what anchors actually exist
+
+   ```
+   grep -on 'id="[^"]*"' _site/page-slug/index.html
+   ```
+
+   Find template generating the links
+
+   ```
+   grep -rn "distinct identifier string" _includes _pages _templates
+   ```
+
+### Step 4: Apply Appropriate Fix Strategy
+
+#### Option A: Fix the Data (Recommended for Project Links)
+
+Update dependency names to match actual project slugs:
+
+```yaml
+# Before
+deps: [jekyll-asciidoc-ui, AsciiDocsy]
+
+# After
+deps: [jekyll-asciidoc-ui, asciidocsy-jekyll-theme]
+```
+
+#### Option B: Fix the Template
+
+Update link generation to use project lookup:
+
+```liquid
+{% assign dep_project = projects | where: 'slug', dep | first %}
+{% unless dep_project %}{% assign dep_project = projects | where: 'name', dep | first %}{% endunless %}
+<a href="/projects/#{{ dep_project.slug | default: dep | slugify }}">
+```
+
+#### Option C: Fix the Anchors/IDs
+
+Update actual IDs to match expected links. Use this solution only when the link source is wrong or the target anchor ID is wrong where it is designated or missing.
+
+Misspelled link source
+
+```asciidoc
+See xref:sectione-one[Section One] for details.
+```
+
+Misspelled anchor ID
+
+```asciidoc
+[[secton-one]]
+=== Section One
+```
+
+## Data-Driven Link Debugging
+
+### YAML Data Sources
+
+Key files that commonly generate broken links:
+
+**`_data/docops-lab-projects.yml`** :
+   Project dependencies and metadata
+
+**`_data/pages/*.yml`** :
+   Navigation and cross-references
+
+**Individual frontmatter** :
+   Local link definitions
+
+### Dependency Tracing Process
+
+1. **Identify the broken link pattern** : `#missing-anchor`
+2. **Find the data source** : Search YAML files for dependency names
+3. **Trace template processing** : Follow Liquid template logic
+4. **Compare with reality** : Check actual generated IDs
+5. **Apply data fix** : Update dependency to match actual slug
+
+### Example Trace: AsciiDocsy Links
+
+```bash
+# 1. Broken link found
+# internally linking to /projects/#asciidocsy
+
+# 2. Find template source
+grep -r "#asciidocsy" _includes/
+# Found in: _includes/project-profile.html line 76
+
+# 3. Check template logic
+# href="/projects/#{{ dep | slugify }}"
+
+# 4. Find data source
+grep -n "AsciiDocsy" _data/docops-lab-projects.yml
+# Found: deps: [..., AsciiDocsy]
+
+# 5. Check actual anchor
+grep 'id=".*asciidoc.*"' _site/projects/index.html
+# Found: id="asciidocsy-jekyll-theme"
+
+# 6. Fix: Change AsciiDocsy → asciidocsy-jekyll-theme
+```
+
+## Pre-Publication Link Strategy
+
+For links to resources not yet available:
+
+1. **Tag with FIXME-PREPUB** : Add comments for easy identification
+2. **Document in notes** : Track what needs to be updated at publication
+3. **Use conditional logic** : Hide pre-pub links in production builds
+
+```asciidoc
+// FIXME-PREPUB: Update when DocOps/box repository is published
+See the link:https://github.com/DocOps/box[DocOps Box repository] for details.
+```
+
+## Validation and Testing
+
+### Rebuild and Verify
+
+```bash
+# Rebuild site with fixes
+bundle exec rake build
+
+# Re-run validation
+bundle exec rake labdev:lint:html
+
+# Check specific fix
+grep "#fixed-anchor" _site/target-page.html
+```
+
+### Test Cycle
+
+1. Fix high-impact patterns first (3+ occurrences)
+2. Rebuild and validate after each batch of fixes
+3. Document fixes for future reference
+4. Test both internal and external link resolution
+
+## Prevention Strategies
+
+### Development Practices
+
+**Consistent naming** :
+   Align dependency names with actual project slugs
+
+**Template validation** :
+   Test link generation logic with sample data
+
+**Documentation standards** :
+   Document expected anchor patterns
+
+**Regular validation** :
+   Include link checking in CI/CD pipelines
+
+### Configuration Management
+
+**Default values** :
+   Define link patterns in configuration rather than hardcoding
+
+**Validation rules** :
+   Create checks for common link anti-patterns
+
+**Documentation** :
+   Maintain mapping between logical names and actual slugs
+
+This systematic approach transforms broken link debugging from a frustrating manual process into a predictable, methodical workflow that scales across projects and team members.
+

data/docs/agent/skills/fix-jekyll-asciidoc-build-errors.md

@@ -0,0 +1,23 @@
+# Fix Jekyll AsciiDoc Build Errors
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+As an AI agent, you can help fix Asciidoctor errors in Jekyll builds.
+
+1. Perform a basic Jekyll build that writes verbose output to a local file.
+
+Example with config option
+
+```
+bundle exec jekyll build --verbose --config configs/jekyll.yml > .agent/scratch/jekyll-build.log 2>&1
+```
+
+Note the `2>&1` at the end of the command, which ensures that both standard output and error messages are captured in the log file.
+2. Run the analysis task on the exported file.
+
+```
+bundle exec rake 'labdev:lint:logs[jekyll-asciidoc,.agent/scratch/jekyll-build.log]'
+```
+3. Open the YAML file relayed in the response message (example: `Jekyll AsciiDoc issues report generated: .agent/reports/jekyll-asciidoc-issues-20251214_085323.yml`).
+4. Follow the instructions in the report to address the issues found.
+

data/docs/agent/skills/fix-spelling-issues.md

@@ -0,0 +1,13 @@
+# Fix Spelling Issues in Documentation
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+As an AI agent, you can help DocOps Lab developers fix spelling issues in documentation by following the procedure below.
+
+1. Use the spellcheck task to generate a spelling report.
+
+```
+bundle exec rake labdev:lint:spellcheck
+```
+2. Follow the prompts in the generated report.
+