ace-handbook 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d7a79a21b2d55e4fd1a583f2825f10eff4e163629b49520c7aa50096e6472c
-  data.tar.gz: 38696630f7cad28c282e6904195c397d808d667f6fe5c9543b31aaba3bf0d97c
+  metadata.gz: 601dc9817570da785077875d586005bd52693f9fda174cbd6c6ab1a52caff72c
+  data.tar.gz: 6fac18f1c2b84444de63d4922f959c0ea75d7ac949778ebb614d60a5a27a06aa
 SHA512:
-  metadata.gz: a6f780c0d782d95b6d9799e12b5d9f5787328b953d02dcd77720961a428bded1004793cf91928d321494feb1eb6c1582d48ede4667514b5a456ad3e91a2e9cc6
-  data.tar.gz: 2137a2d0924441c6f462f5bfa682b809f429d93ad1585a71ebdd82a09b2e8df8c217508a08c81b9a65b226ce788f1d1c83819cf5e7e2b0ad330e00db1e6a8f9b
+  metadata.gz: 0d81b467e7f3a34c6856a37732072703ce582088a9c8a1706e5f9c6c2c3cdd1b2b7d24f4067202b2e9594d3b3df6c4a1c9fd8282ab9a912d43856a5f783c5a16
+  data.tar.gz: 41c864dc6543d3de1b63af4e9107c34f3b4ebc7c03c3861424c005db288ef557f4509158d67869cf86b052242832e397876c1e6f95ba7fa7f62f5c75d0b23479

data/CHANGELOG.md

@@ -1,4 +1,5 @@
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -6,18 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-03-28
+
+### Changed
+
+- Migrated most RubyGems publish decision logic into `wfi://release/rubygems-publish`, keeping `as-release-rubygems-publish` as a thin workflow wrapper.
+
+### Technical
+
+- Removed skill-local pending-release-discovery preference logic and aligned the workflow with build-first + single-OTP publish behavior.
+
+## [0.20.0] - 2026-03-28
+
+### Added
+
+- Added `bin/ace-rubygems-needs-release` to derive pending ACE RubyGems releases from a single remote snapshot instead of querying each gem individually.
+
+### Changed
+
+- Updated the RubyGems publish workflow to prefer the helper script when available and corrected the fallback `gem search --exact` guidance.
+- Updated `as-release-rubygems-publish` skill instructions to prefer the helper script for pending-release discovery.
+
 ## [0.19.0] - 2026-03-23
 
 ### Added
+
 - New use case in README documenting `ace-handbook sync` and `ace-handbook status` CLI commands.
 - Added `as-release`, `as-release-bump-version`, `as-release-rubygems-publish`, and `as-release-update-changelog` to the handbook skills reference table.
 - Re-recorded getting-started demo GIF showcasing provider status and sync workflows.
 
 ### Fixed
-- Fixed broken `[ace-nav](../ace-nav)` cross-link in README — corrected to `[ace-nav](../ace-support-nav)`.
-- Fixed incorrect `ace-integration-*` package reference in README — corrected to `ace-handbook-integration-*`.
+
+- Fixed broken `[ace-nav](../ace-nav)` cross-link in README -- corrected to `[ace-nav](../ace-support-nav)`.
+- Fixed incorrect `ace-integration-*` package reference in README -- corrected to `ace-handbook-integration-*`.
 
 ### Changed
+
 - Aligned gemspec description wording with summary for consistency.
 - Removed stale `mise` prerequisite from `docs/getting-started.md`.
 - Rewrote demo tape to focus on `ace-handbook status` and `ace-handbook sync --provider pi`.
@@ -25,23 +50,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.18.3] - 2026-03-23
 
 ### Changed
+
 - Refreshed `README.md` to the current package layout pattern with quick-link navigation, use-case framing, and normalized section order.
 
 ## [0.18.2] - 2026-03-22
 
 ### Changed
+
 - Updated `docs/getting-started.md` to remove contradictory `mise exec --` prose and align onboarding guidance with direct `ace-*` command usage.
 - Documented intentional retirement of projected provider `as-idea-capture` and `as-idea-capture-features` skill files after canonical source removal.
 
 ## [0.18.1] - 2026-03-22
 
 ### Changed
+
 - Remove `mise exec --` wrapper from test fixture strings and canonical skill docs.
 - Document intentional retirement of projected provider `as-idea-capture` and `as-idea-capture-features` skill files after canonical source removal.
 
 ## [0.18.0] - 2026-03-22
 
 ### Changed
+
 - Reworked `ace-handbook` documentation into a landing-page README with package-focused messaging and links to dedicated docs.
 - Added `docs/getting-started.md`, `docs/usage.md`, and `docs/handbook.md` with tutorial and workflow/skill reference coverage.
 - Added demo assets under `docs/demo/` and aligned examples to the current `ace-nav resolve/list` command pattern.
@@ -50,181 +79,219 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.17.1] - 2026-03-21
 
 ### Added
+
 - Add RubyGems publish workflow (`wfi://release/rubygems-publish`) for publishing ACE gems in dependency order with credential verification, conflict detection, and dry-run support.
 - Add `as-release-rubygems-publish` skill for invoking the RubyGems publish workflow.
 
 ## [0.17.0] - 2026-03-21
 
 ### Changed
+
 - Added initial `TS-HANDBOOK-001` value-gated smoke E2E coverage for `ace-handbook` CLI help and status command contracts.
 
 ## [0.16.1] - 2026-03-18
 
 ### Changed
+
 - Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
 
 
 ## [0.16.0] - 2026-03-18
 
 ### Changed
+
 - Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
 
 
 ## [0.15.9] - 2026-03-18
 
 ### Fixed
+
 - Updated `cli-support-cli.g.md` guide to remove stale `DryCli::` namespace prefix from `VersionCommand` and `HelpCommand` class references.
 
 ## [0.15.8] - 2026-03-17
 
 ### Changed
+
 - Updated `cli-support-cli.g.md` examples to the current `ace-support-cli` API (`RegistryDsl`, `Runner`, and `coerce_types`).
 - Updated review workflow docs to reflect 15-minute timeout guidance for long PR review runs.
 
 ## [0.15.7] - 2026-03-15
 
 ### Changed
+
 - Migrated CLI framework from dry-cli to ace-support-cli
 
 ## [0.15.6] - 2026-03-13
 
 ### Changed
+
 - Updated handbook-owned canonical skills to explicitly run bundled workflows in the current project and execute them end-to-end.
 
 ### Technical
+
 - Refreshed provider sync and status collector regression coverage for the new compact canonical skill execution template.
 
 ## [0.15.5] - 2026-03-13
 
 ### Changed
+
 - Removed provider-specific skill body rendering so projected provider skills once again apply frontmatter overrides while preserving the canonical skill body unchanged.
 - Updated the canonical `as-release` skill to use the unified arguments / variables / execution structure with explicit workflow-execution guidance.
 - Limited provider-specific forking for `as-release` to Claude frontmatter only.
 
 ### Technical
+
 - Simplified handbook projection coverage to validate frontmatter override projection and canonical body preservation instead of provider-specific body rendering.
 
 ## [0.15.4] - 2026-03-13
 
 ### Changed
+
 - Strengthened projected workflow skill instructions for Codex delegated execution and forked provider contexts so generated provider skills explicitly load and execute workflows in the current project instead of only reading or summarizing them.
 
 ### Technical
+
 - Added projection regression coverage for strong workflow-execution rendering in both Codex `context: ace-llm` mode and provider `context: fork` mode.
 
 ## [0.15.3] - 2026-03-13
 
 ### Changed
+
 - Render Codex `ace-llm` skills from canonical frontmatter by deriving uppercase variables from `argument-hint` and generating `## Variables` / `## Instructions` sections for projected Codex skills.
 
 ### Technical
+
 - Added projection regression coverage for `context: ace-llm` rendering and argument-hint-derived Codex variable generation.
 
 ## [0.15.2] - 2026-03-12
 
 ### Fixed
+
 - Preserved conditional `--sandbox` workflow routing in provider-synced skill projections so generated Claude and Codex skills keep the canonical E2E execute path.
 
 ### Technical
+
 - Added provider-sync regression coverage for conditional workflow bodies in projected skills.
 
 ## [0.15.1] - 2026-03-12
 
 ### Changed
+
 - Updated handbook README, workflow docs, and guidance to document bundle-first workflow usage and the current handbook structure.
 
 ## [0.15.0] - 2026-03-12
 
 ### Added
+
 - Added Codex-specific delegated execution metadata to the canonical `as-release-bump-version` and `as-release-update-changelog` skills so the generated Codex skills run in fork context on `gpt-5.3-codex-spark`.
 
 ## [0.14.1] - 2026-03-12
 
 ### Technical
+
 - Updated provider sync regression coverage to verify provider-specific `context` and `model` overrides on projected git-commit skills and to keep generated provider output free of canonical `integration` metadata.
 
 ## [0.14.0] - 2026-03-12
 
 ### Changed
+
 - Changed canonical handbook skill inventory to load from registered `skill://` sources via `ace-support-nav` instead of scanning monorepo package directories directly.
 
 ### Technical
+
 - Added nav-backed inventory regression coverage and explicit skill-source registration fixtures for handbook sync/status tests.
 
 ## [0.13.1] - 2026-03-12
 
 ### Technical
+
 - Added regression coverage for the `.agent/skills` retirement so handbook sync/status changes are exercised against provider-native skill trees only.
 
 ## [0.13.0] - 2026-03-12
 
 ### Added
+
 - Added canonical skill inventory counts by `source` to `ace-handbook status` output and JSON responses.
 
 ### Changed
+
 - Expanded provider status reporting to show expected, installed, in-sync, outdated, missing, and extra skill counts, including comparisons through symlinked provider directories.
 
 ## [0.12.0] - 2026-03-10
 
 ### Added
+
 - Added a public `ace-handbook` CLI with `sync` and `status` commands for projecting canonical package skills into provider-native folders.
 - Added provider manifest discovery and sync/status coverage for handbook integrations, including replacement of legacy provider skill symlinks with real provider directories.
 
 ### Changed
+
 - Moved handbook integration execution to `ace-handbook` while provider packages now supply thin provider manifests for projection targets.
 
 ## [0.11.0] - 2026-03-10
 
 ### Added
+
 - Added canonical handbook-owned skills for handbook management, release workflows, and research/delivery orchestration.
 
 
 ## [0.10.0] - 2026-03-08
 
 ### Added
+
 - New `release/publish` workflow for coordinated multi-package releases that auto-detect modified packages, update package and root changelogs, and finish with one release commit.
 
 ### Changed
+
 - `/as-release` now loads `wfi://release/publish`, and release documentation now points to the canonical workflow path.
 
 ## [0.9.9] - 2026-03-04
 
 ### Changed
+
 - Update `perform-delivery` workflow PR skill references from `/ace-git-create-pr` to `/ace-github-pr-create`
 
 ## [0.9.8] - 2026-02-25
 
 ### Changed
+
 - Update `perform-delivery` workflow task lookup guidance to use `ace-task show <ref>` for explicit task selection.
 
 ## [0.9.7] - 2026-02-22
 
 ### Technical
+
 - Update `ace-bundle project` → `ace-bundle load project` in update-docs workflow
 
 ## [0.9.6] - 2026-02-22
 
 ### Changed
+
 - Migrate skill naming and invocation references to hyphenated `ace-*` format (no underscores).
 
 ## [0.9.5] - 2026-02-21
 
 ### Added
+
 - "Redundant computation" root cause category in selfimprove workflow with fix template showing compute-once-pass-explicitly pattern
 
 ## [0.9.4] - 2026-02-20
 
 ### Technical
+
 - Update /ace:create-pr to /ace:git-create-pr in perform-delivery workflow
 
 ## [0.9.3] - 2026-02-20
 
 ### Technical
+
 - Update stale wfi:// references in workflow definition guide
 
 ## [0.9.2] - 2026-02-19
 
 ### Technical
+
 - Namespace workflow instructions into handbook/ subdirectory with updated wfi:// URIs
 - Update skill name references to use namespaced ace:handbook-action format
 
@@ -237,77 +304,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.9.0] - 2026-02-03
 
 ### Added
+
 - Self-improve workflow (`selfimprove.wf.md`) for transforming agent mistakes into system improvements
 
 ## [0.8.0] - 2026-01-31
 
 ### Added
+
 - Multi-agent research synthesis capabilities (Task 254):
+
   - `multi-agent-research.g.md` guide explaining when/how to use parallel agents
   - `research-comparison.template.md` for structured synthesis comparison
   - `parallel-research.wf.md` workflow for setting up parallel agent research
   - `synthesize-research.wf.md` workflow for combining agent outputs
   - `research.wf.md` with single/multi-agent decision criteria
+
 - Template protocol source configuration for ace-handbook templates
 
 ## [0.7.1] - 2026-01-29
 
 ### Fixed
+
 - Refine exit code handling documentation for dry-cli framework with exception-based pattern
 
 ## [0.7.0] - 2026-01-22
 
 ### Added
+
 - New guides extracted from ace-gems.g.md for better discoverability:
+
   - `prompt-caching.g.md` - PromptCacheManager patterns for LLM prompt generation
   - `cli-dry-cli.g.md` - Complete dry-cli framework reference
   - `mono-repo-patterns.g.md` - Mono-repo development patterns and binstubs
+
 - Document IO isolation and testing pyramid patterns
 
 ### Technical
+
 - Lower Ruby version requirement to >= 3.2.0
 
 ## [0.6.0] - 2026-01-18
 
 ### Added
+
 - Add perform-delivery workflow for multi-step delivery tracking with automatic TodoWrite externalization
 
 ### Technical
+
 - Update guides for bundle terminology
 
 ## [0.5.2] - 2026-01-16
 
 ### Changed
+
 - Rename context: to bundle: keys in configuration files
 
 ## [0.5.1] - 2026-01-08
 
 ### Fixed
+
 - Fixed `guide://` protocol links in ace-test-runner guides (added `.g` suffix for `.g.md` files)
 - Cross-gem guide:// links now properly resolve to resources with `.g` extension
 
 ## [0.5.0] - 2026-01-08
 
 ### Added
+
 - Migrated 10 generic guides from dev-handbook to handbook/guides/
+
   - ai-agent-integration.g.md, atom-pattern.g.md, changelog.g.md
   - coding-standards.g.md, debug-troubleshooting.g.md, error-handling.g.md
   - performance.g.md, quality-assurance.g.md, strategic-planning.g.md
+
 - Migrated 5 meta-guides to handbook/guides/meta/
+
   - agents-definition.g.md, guides-definition.g.md, markdown-definition.g.md
   - tools-definition.g.md, workflow-instructions-definition.g.md
+
 - Guide subdirectories with language-specific content (ruby, rust, typescript)
 - initialize-project-structure.wf.md workflow for project setup
 - Templates: cookbooks/cookbook.template.md, completed-work-documentation.md
 - Template discovery protocol (.ace-defaults/nav/protocols/tmpl-sources/)
 
 ### Changed
+
 - Consolidates dev-handbook content into ace-handbook gem
 - All development guides now distributed with gem installation
 
 ## [0.4.0] - 2026-01-03
 
 ### Added
+
 - Guides support with handbook/guides/ directory
 - workflow-context-embedding.g.md guide for embed_document_source pattern
 - Guide discovery protocol (.ace-defaults/nav/protocols/guide-sources/ace-handbook.yml)
@@ -315,6 +402,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.3.0] - 2026-01-03
 
 ### Changed
+
 - **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
 - Standardized gemspec file patterns with deterministic Dir.glob
 - Added MIT LICENSE file
@@ -328,33 +416,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.0] - 2025-11-05
 
 ### Added
+
 - Initial release of ace-handbook gem as pure workflow package
 - 6 handbook management workflows accessible via wfi:// protocol:
+
   - `wfi://manage-guides` - Create and update development guides
   - `wfi://review-guides` - Review guides for quality and consistency
   - `wfi://manage-workflow-instructions` - Create and validate workflow files
   - `wfi://review-workflows` - Review workflow instructions
   - `wfi://manage-agents` - Create and update agent definitions
   - `wfi://update-handbook-docs` - Update handbook README and structure
+
 - Path references updated for project-relative usage
 - Complete gem structure following ACE patterns
 - Comprehensive documentation and usage examples
 - Auto-discovery support through ace-nav gem
 
 ### Changed
+
 - Migrated workflows from dev-handbook/.meta/wfi/ to installable gem
 - Updated path references to be project-root relative
 - Removed dev-handbook specific dependencies
 
 ### Removed
+
 - Moved `update-tools-docs.wf.md` to ace-docs package (tools documentation management)
 - Moved `update-integration-claude.wf.md` to ace-integration-claude package (Claude Code integration)
 
 ### Fixed
+
 - Added ace-nav protocol registration (.ace.example/nav/protocols/wfi-sources/ace-handbook.yml)
 - Updated gemspec to include protocol registration files for proper discovery
 
 ### Technical Details
+
 - Pure workflow package with no Ruby runtime dependencies
 - Auto-discovery via ace-nav through handbook/workflow-instructions/ directory
 - Protocol registration enables ace-nav to discover workflows from installed gem

data/README.md

@@ -3,7 +3,7 @@
 
   Standardized workflows for creating and managing guides, workflow instructions, and agent definitions.
 
-  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
 
   <a href="https://rubygems.org/gems/ace-handbook"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-handbook.svg" /></a>

data/handbook/guides/cli-dry-cli.g.md

@@ -16,6 +16,7 @@ Complete reference for implementing CLI interfaces in ace-* gems using dry-cli.
 All ACE CLI gems use dry-cli. See [ADR-023](../../../docs/decisions/ADR-023-dry-cli-framework.md) for decision rationale.
 
 **Two patterns:**
+
 - **Multi-command**: Subcommand tools (ace-bundle, ace-taskflow)
 - **Single-command**: One-action tools (ace-git-commit, ace-search)
 
@@ -73,6 +74,7 @@ end
 ```
 
 **Exe wrapper:**
+
 ```ruby
 #!/usr/bin/env ruby
 require "ace/gem"
@@ -113,6 +115,7 @@ end
 ```
 
 **Exe wrapper:**
+
 ```ruby
 #!/usr/bin/env ruby
 require "ace/gem"
@@ -232,6 +235,7 @@ end
 ```
 
 **Exe wrapper catches exceptions:**
+
 ```ruby
 #!/usr/bin/env ruby
 require "ace/gem"

data/handbook/guides/cli-support-cli.g.md

@@ -16,6 +16,7 @@ Complete reference for implementing CLI interfaces in ace-* gems using ace-suppo
 All ACE CLI gems use ace-support-cli. See [ADR-023](../../../docs/decisions/ADR-023-ace-support-cli-framework.md) for decision rationale.
 
 **Two patterns:**
+
 - **Multi-command**: Subcommand tools (ace-bundle, ace-taskflow)
 - **Single-command**: One-action tools (ace-git-commit, ace-search)
 
@@ -73,6 +74,7 @@ end
 ```
 
 **Exe wrapper:**
+
 ```ruby
 #!/usr/bin/env ruby
 require "ace/gem"
@@ -113,6 +115,7 @@ end
 ```
 
 **Exe wrapper:**
+
 ```ruby
 #!/usr/bin/env ruby
 require "ace/gem"
@@ -232,6 +235,7 @@ end
 ```
 
 **Exe wrapper catches exceptions:**
+
 ```ruby
 #!/usr/bin/env ruby
 require "ace/gem"

data/handbook/guides/coding-standards/ruby.md

@@ -33,7 +33,7 @@ addition to the generic standards in `../coding-standards.md`.
 
 ## Performance Tips
 
-- Prefer `each` over `map` when you don’t need the new array.
+- Prefer `each` over `map` when you don't need the new array.
 - Avoid creating unnecessary objects in hot code paths.
 
 ---

data/handbook/guides/coding-standards.g.md

@@ -22,15 +22,23 @@ in the relevant `dev-taskflow/` directory or linked from the `docs/blueprint.md`
 ## General Principles
 
 - **Clarity & Readability:** Write code that is easy for others (and your future self) to understand. Use
+
   meaningful variable names, keep functions/methods short and focused, and add comments where logic is
   complex or non-obvious.
+
 - **Consistency:** Follow established patterns and conventions within the project. If using a style guide tool
+
   (like StandardRB, RuboCop), adhere to its rules.
+
 - **Simplicity (KISS):** Avoid unnecessary complexity. Prefer straightforward solutions unless a more complex
+
   approach offers significant, justifiable benefits (e.g., performance).
+
 - **Don\'t Repeat Yourself (DRY):** Abstract common logic into reusable functions, methods, or classes.
 - **Modularity:** Design components with clear responsibilities and well-defined interfaces. Aim for loose
+
   coupling and high cohesion.
+
 - **Testability:** Write code that is easy to test. Use dependency injection and avoid tight coupling to
 
 ## Language-Specific Coding Standards
@@ -45,9 +53,12 @@ Please refer to the relevant guide for your language:
 
 - **Indentation:** Use consistent indentation (e.g., 2 spaces for Ruby).
 - **Line Length:** Adhere to a reasonable line length limit (e.g., 100-120 characters) to improve
+
   readability.
+
 - **Whitespace:** Use whitespace effectively to separate logical blocks of code.
 - **Tooling:** Utilize automated formatters and linters (e.g., StandardRB, Prettier) to enforce
+
   consistency. Configure these tools via project configuration files (e.g., `.standard.yml`, `.prettierrc`).
 
 ## Error Handling
@@ -75,6 +86,7 @@ Please refer to the relevant guide for your language:
 
 - Follow a logical directory structure (e.g., separating library code, tests, configuration, documentation).
 - Use clear and consistent file naming conventions.
+
 Refer to the project's `docs/blueprint.md` for the specific structure.
 
 ## AI-Assisted Development Collaboration
@@ -83,26 +95,41 @@ When working with AI coding agents (like Cursor, Claude, etc.), treat them as co
 to a junior developer needing clear guidance.
 
 - **Plan Before Prompting:** Thoroughly plan the task, including outlining steps, defining requirements, and
+
   identifying relevant context *before* asking the AI to generate or modify code. This aligns with the
   "Slow Vibe Coding" principle mentioned in Project Management.
+
 - **Provide Context:** Give the AI sufficient context, including relevant code snippets, project structure
+
   (`docs/blueprint.md`), architecture (`docs/architecture.md`), existing patterns, and the
   specific task definition (`.md` file within `dev-taskflow`).
+
 - **Use Specific, Concise Instructions:** Avoid vague requests. Break down complex tasks into smaller,
+
   well-defined steps. Use clear action verbs and specify the desired outcome. Consider using "prompt hygiene"
   like "ONLY IMPLEMENT EXACTLY THIS STEP" for focused changes.
+
 - **Structured Prompts:** Structure prompts clearly, defining the AI\'s role, the objective, step-by-step instructions,
+
   and the desired output format (XML is often preferred by models like GPT-4.1). Include examples (few-shot learning)
   where appropriate.
+
 - **Review Rigorously:** Review AI-generated code with the same scrutiny as human-written code. Check for
+
   correctness, adherence to standards, edge cases, security, and performance implications. Do not blindly
   trust AI output.
+
 - **Iterate and Refine:** Expect to iterate. Provide constructive feedback on the AI\'s output to guide it
+
   towards the desired solution. Ask for explanations of its logic to learn and verify understanding.
+
 - **Leverage Strengths:** Use AI for tasks it excels at (e.g., boilerplate code, implementing well-defined
+
   algorithms, refactoring based on clear rules) but rely on human oversight for complex design decisions
   and architectural planning.
+
 - **Avoid "Hacky" Prompts:** Modern models respond better to clear instructions than tricks like excessive
+
   capitalization or emotional appeals.
 
 Refer to the [Project Management Guide](guide://project-management) for how AI collaboration fits

data/handbook/guides/debug-troubleshooting.g.md

@@ -16,7 +16,7 @@ debugging to seeking help.
 
 | Step | What to do | Why |
 |------|------------|-----|
-| **1  Understand the system** | Skim docs/architecture first | You can’t debug what you don’t grasp. |
+| **1  Understand the system** | Skim docs/architecture first | You can't debug what you don't grasp. |
 | **2  Make it fail on demand** | Reproduce the bug and minimise the input or scenario | Gives you a quick feedback loop & future test. |
 | **3  Collect evidence** | Read stack traces, logs, error codes | Surface clues without touching code. |
 | **4  Check recent changes/config** | Roll back toggles, feature flags, deployments | Regressions are usually fresh. |
@@ -30,13 +30,20 @@ debugging to seeking help.
 ## Elaborations on Key Steps
 
 * **Step 2: Make it fail on demand:** This is crucial for effective testing. Aim for the *simplest possible*
+
   reproducible case. This often forms the basis of a new regression test (see Step 8).
+
 * **Step 3 & 4: Collect evidence & Check recent changes:** Don't underestimate logs, configuration files, and
+
   recent commits (`git log`, `git blame`). Many issues are regressions introduced by recent changes.
+
 * **Step 8: Validate & Regress-Test:** After applying a fix, *always* run the minimal failing case you created in
+
   Step 2 to confirm the specific issue is resolved. Then, run the broader test suite (e.g., `bin/rspec`, `npm test`)
   to check for unintended side-effects. Refer to the [Testing Guidelines Guide](testing.g.md) for more details.
+
 * **Step 10: Escalate or Rubber Duck:** If you're stuck after diligently following the steps:
+
   * **Rubber Ducking:** Explain the problem out loud (to yourself, a pet, or an inanimate object). This often
     clarifies your thinking.
   * **AI Assistance:** Consult an AI agent. Use structured prompts, providing the context (code, error, steps taken).
@@ -48,8 +55,11 @@ debugging to seeking help.
 ## Utilizing Documentation and Research
 
 * **Internal Docs:** Before extensive debugging, always check project-specific documentation (`README.md`,
+
   architecture diagrams in project docs, specific guides via `guide://` protocol).
+
 * **External Research:** Use search engines effectively. Formulate precise queries including error messages,
+
   technology names, and library versions.
 
 ## Language-Specific Considerations