ace-handbook 0.19.0

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

@@ -0,0 +1,134 @@
+---
+doc-type: guide
+title: General Coding Standards
+purpose: Documentation for ace-handbook/handbook/guides/coding-standards.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# General Coding Standards
+
+## Goal
+
+This guide outlines the fundamental principles and standards for writing clean, readable, maintainable,
+and consistent code within this project. Adhering to these standards facilitates collaboration
+(human-human and human-AI) and long-term project health.
+
+This document outlines general coding standards applicable across the project. Project-specific
+conventions or language-specific rules beyond these general principles may be documented
+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
+
+Language-specific idioms, conventions, and tool recommendations have been moved to dedicated sub-guides.
+Please refer to the relevant guide for your language:
+
+- [Ruby Coding Standards](./coding-standards/ruby.md)
+- [TypeScript Coding Standards](./coding-standards/typescript.md)
+
+## Formatting & Style
+
+- **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
+
+- Use specific, informative error classes. Define a base error class for the project/library.
+- Provide context with errors (e.g., relevant data, operation being performed).
+- Handle errors appropriately (log, retry, raise, return error values) based on the context.
+- See [Error Handling Guide](./error-handling.g.md) for more details.
+
+## Testing
+
+- Write tests for new code (unit, integration, E2E as appropriate).
+- Ensure tests cover primary functionality, edge cases, and error conditions.
+- Keep tests independent and fast.
+- See [Testing Guidelines](guide://testing) for more details.
+
+## Documentation
+
+- Document public APIs (classes, methods, modules) using standard documentation tools (e.g., YARD for Ruby).
+- Add comments to explain complex logic or non-obvious decisions within method bodies.
+- Keep documentation up-to-date with code changes.
+- See [Documentation Standards](guide://documentation) for more details.
+
+## File Organization
+
+- 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
+
+When working with AI coding agents (like Cursor, Claude, etc.), treat them as collaborative partners, often akin
+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
+into the task workflow.
+
+(Example structure - adjust based on project)
+
+```text
+project-root/
+├── lib/          # Core library code
+│   └── my_module/
+├── spec/         # Tests
+│   ├── unit/
+│   ├── integration/
+│   └── support/
+├── config/       # Configuration files
+├── docs/         # User-facing documentation
+├── ace-handbook/     # Development handbook (internal docs)
+├── bin/          # Executable scripts
+└── Rakefile / Makefile / etc. # Build/task runner configuration
+```
+
+## Related Documentation
+
+- [Error Handling Guide](./error-handling.g.md)
+- [Testing Guidelines](guide://testing)
+- [Documentation Standards](guide://documentation)
+- [Temporary File Management Guidelines](./temporary-file-management.g.md)
+- [Project Management Guide](guide://project-management) (AI Collaboration context)

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

@@ -0,0 +1,62 @@
+---
+doc-type: guide
+title: High-Level Troubleshooting Workflow
+purpose: Documentation for ace-handbook/handbook/guides/debug-troubleshooting.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# High-Level Troubleshooting Workflow
+
+This guide provides a general, technology-agnostic workflow for approaching development challenges, from initial
+debugging to seeking help.
+
+## Universal Troubleshooting Steps
+
+| Step | What to do | Why |
+|------|------------|-----|
+| **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. |
+| **5  Divide & conquer** | Bisect the call‑graph, comment blocks, or binary‑search commits | Narrows the suspect area fast. |
+| **6  Form a hypothesis & probe** | Insert breakpoints/print‑debug, **do not "fix" yet** | Prevents cargo‑cult patches. |
+| **7  Change one thing, re‑test** | One variable at a time, audit the steps | Keeps cause‑and‑effect clear. |
+| **8  Validate & regress‑test** | Run the original minimal case + full suite | Confirms the root cause, avoids side‑effects. |
+| **9  Document & share** | Note root cause, fix, follow‑ups | Future devs (and you) will thank you. |
+| **10  Escalate or rubber‑duck** | Fresh eyes or an AI agent when stuck | External perspective breaks tunnel vision. |
+
+## 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).
+    Reference the `[ask-an-agent workflow - PATH NEEDED]` for best practices.
+  * **Human Escalation:** If AI doesn't help, reach out to teammates. Prepare by summarizing the problem, what
+    you've tried (Steps 1-9), and specific questions. Check the `CONTRIBUTING.md` or team documentation for
+    preferred communication channels.
+
+## 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
+
+While this guide provides a universal workflow, specific tools and techniques vary by language. For detailed
+guidance, refer to the language-specific troubleshooting sections:
+
+* [Ruby Troubleshooting](troubleshooting/ruby.md) (*To be created/moved from research*)
+* [Rust Troubleshooting](troubleshooting/rust.md) (*To be created/moved from research*)
+* [TypeScript Troubleshooting](troubleshooting/typescript.md) (*To be created/moved from research*)

data/handbook/guides/error-handling/ruby.md

@@ -0,0 +1,29 @@
+# Ruby Error Handling Examples
+
+This file provides Ruby-specific examples related to the main [Error Handling Guide](../error-handling.g.md).
+
+* Mechanism: begin/rescue/ensure/raise
+* Standard Library: StandardError hierarchy
+
+```ruby
+class CustomError < StandardError
+  attr_reader :context
+
+  def initialize(message = "Something went wrong", context = {})
+    super(message)
+    @context = context
+  end
+end
+
+begin
+  # Code that might raise an error
+  raise CustomError.new("Failed operation", { data: 'example' }) if some_condition
+rescue CustomError => e
+  puts "Caught custom error: #{e.message}, Context: #{e.context}"
+rescue StandardError => e
+  puts "Caught other standard error: #{e.message}"
+ensure
+  # Cleanup code
+  puts "Ensuring cleanup"
+end
+```

data/handbook/guides/error-handling/rust.md

@@ -0,0 +1,59 @@
+# Rust Error Handling Examples
+
+This file provides Rust-specific examples and considerations related to the main [Error Handling Guide](../error-handling.g.md).
+
+* **Mechanisms:** `Result<T, E>` enum for recoverable errors, `panic!` macro for unrecoverable errors.
+* **Libraries:** `thiserror`, `anyhow` for custom error types and convenience.
+
+```rust
+use std::fmt;
+
+// Example using standard library Result and Box<dyn Error>
+fn do_something(input: &str) -> Result<String, Box<dyn std::error::Error>> {
+    if input.is_empty() {
+        return Err("Input cannot be empty".into()); // Simple error conversion
+    }
+    // ... potentially complex logic ...
+    Ok(format!("Processed {}", input))
+}
+
+// Example custom error enum (could use 'thiserror' crate for convenience)
+#[derive(Debug)]
+enum ProcessingError {
+    InvalidInput(String),
+    InternalError(String),
+}
+
+impl fmt::Display for ProcessingError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self {
+            ProcessingError::InvalidInput(msg) => write!(f, "Invalid Input: {}", msg),
+            ProcessingError::InternalError(msg) => write!(f, "Internal Error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for ProcessingError {}
+
+fn do_something_custom(input: &str) -> Result<String, ProcessingError> {
+    if input.is_empty() {
+        return Err(ProcessingError::InvalidInput("Input was empty".to_string()));
+    }
+    // ...
+    Ok(format!("Processed {}", input))
+}
+
+fn main() {
+    match do_something_custom("") {
+        Ok(result) => println!("Success: {}", result),
+        Err(e) => println!("Error: {}", e),
+    }
+
+    // Example of propagating errors with `?` operator
+    let result = do_something_custom("valid").expect("Should succeed");
+    println!("Result via expect: {}", result);
+
+    // Panics for unrecoverable errors (use sparingly)
+    // panic!("This is an unrecoverable error!");
+}
+```

data/handbook/guides/error-handling/typescript.md

@@ -0,0 +1,38 @@
+# TypeScript Error Handling Examples
+
+This file provides TypeScript-specific examples related to the main [Error Handling Guide](../error-handling.g.md).
+
+* **Mechanism:** try/catch/finally/throw
+* **Custom Errors:** Extend the built-in Error class.
+
+```typescript
+class CustomError extends Error {
+  context: Record<string, any>;
+
+  constructor(message: string, context: Record<string, any> = {}) {
+    super(message);
+    this.name = 'CustomError'; // Important for identifying error type
+    this.context = context;
+    // Ensure the prototype chain is set correctly
+    Object.setPrototypeOf(this, CustomError.prototype);
+  }
+}
+
+try {
+  // Code that might throw an error
+  if (someCondition) {
+    throw new CustomError('Failed operation', { data: 'example' });
+  }
+} catch (error) {
+  if (error instanceof CustomError) {
+    console.error(`Caught custom error: ${error.message}, Context:`, error.context);
+  } else if (error instanceof Error) {
+    console.error(`Caught other error: ${error.message}`);
+  } else {
+    console.error('Caught unknown error:', error);
+  }
+} finally {
+  // Cleanup code
+  console.log('Ensuring cleanup');
+}
+```

data/handbook/guides/error-handling.g.md

@@ -0,0 +1,207 @@
+---
+doc-type: guide
+title: Error Handling Guidelines
+purpose: Documentation for ace-handbook/handbook/guides/error-handling.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Error Handling Guidelines
+
+## Goal
+
+This guide outlines the fundamental principles and standards for handling errors consistently and effectively
+throughout the project, ensuring robustness, debuggability, and a good user experience.
+
+## Exception Hierarchy
+
+Establish a clear hierarchy for custom exceptions or error types specific to your application or
+library. This allows for more granular error handling.
+
+- Define a base error class/type for your application (e.g., `MyAppError`).
+- Create specific error subclasses that inherit from the base error (e.g., `ConfigurationError`, `ApiError`, `DatabaseError`).
+- Include relevant context within your error objects (see 'Rich Context' below).
+
+```javascript
+// Pseudo-code example hierarchy
+class MyAppError extends Error {}
+class ConfigurationError extends MyAppError {}
+class AgentError extends MyAppError {
+  constructor(message, context = {}) {
+    super(message);
+    this.context = context;
+  }
+}
+class ToolError extends MyAppError {}
+class ExternalServiceError extends MyAppError {
+  constructor(message, requestId = null) {
+    super(message);
+    this.requestId = requestId;
+  }
+}
+```
+
+## Best Practices
+
+1. **Rich Context**:
+   When catching and logging errors, include as much relevant context as possible without logging sensitive data.
+   This aids debugging.
+
+   ```javascript
+   // Pseudo-code example
+   try {
+     agent.execute(task);
+   } catch (error) {
+     if (error instanceof AgentError) {
+       logger.error("Agent execution failed", {
+         errorMessage: error.message,
+         errorContext: error.context,
+         stackTrace: error.stack.substring(0, 500) // Log part of the stack
+       });
+     } else {
+       logger.error("Unexpected error during agent execution", {
+         errorMessage: error.message,
+         stackTrace: error.stack.substring(0, 500)
+       });
+     }
+   }
+   ```
+
+2. **Recovery Strategies**:
+   Implement strategies to recover from transient errors, especially network-related issues.
+
+   ```javascript
+   // Pseudo-code example: Retry with exponential backoff
+   function executeWithRetry(task) {
+     let retries = 0;
+     const maxRetries = 3;
+     while (true) {
+       try {
+         return agent.execute(task);
+       } catch (error) {
+         if (error instanceof ExternalServiceError && retries < maxRetries) {
+           retries++;
+           const delay = Math.pow(2, retries) * 1000; // Exponential backoff
+           sleep(delay);
+         } else {
+           throw error; // Re-throw if max retries reached or not a recoverable error
+         }
+       }
+     }
+   }
+   ```
+
+3. **Clean Resource Management**:
+   Ensure resources (files, network connections, locks) are properly released, even if errors occur. Use
+   `try...finally` or equivalent language constructs (like Python\'s `with` statement or Go\'s `defer`).
+
+   ```javascript
+   // Pseudo-code example
+   let resource = acquireResource();
+   try {
+     // Use the resource
+     yield resource;
+   } finally {
+     releaseResource(resource);
+   }
+   ```
+
+## Debugging Guide
+
+## Advanced Error Handling Patterns
+
+Consider these patterns for more robust applications:
+
+- **Structured Error Objects:** Define custom error classes/types that include relevant context (e.g., status codes,
+  internal error codes, request IDs). This helps in programmatic error handling and monitoring.
+
+  ```javascript
+  // Pseudo-code example
+  class ApiError extends Error {
+    constructor(message, { statusCode = 500, errorCode = 'UNKNOWN', details = {} } = {}) {
+      super(message);
+      this.statusCode = statusCode;
+      this.errorCode = errorCode;
+      this.details = details;
+    }
+  }
+  // Example usage:
+  // throw new ApiError("User not found", { statusCode: 404, errorCode: 'USER_NOT_FOUND', details: { userId: id } });
+  ```
+
+- **Error Categorization:** Distinguish between:
+  - **Operational Errors:** Expected issues (e.g., invalid input, resource not found) that can often be handled
+    gracefully.
+  - **Programming Errors:** Bugs in the code that need fixing (e.g., type errors, null references).
+  - **System Errors:** External issues (e.g., database unavailable, network failure).
+- **Recovery Strategies:** Implement strategies for transient failures:
+  - **Retry with Backoff:** Automatically retry failed operations (especially network requests) with increasing
+    delays.
+  - **Circuit Breaker:** Prevent repeated calls to a failing service by temporarily blocking
+    requests after a certain number of failures.
+  - **Fallbacks:** Provide a degraded but functional experience if a primary operation
+    fails (e.g., return cached data if a live fetch fails).
+- **Contextual Logging:** Ensure logs capture sufficient context (user ID, request ID,
+  operation parameters) to diagnose errors effectively, while avoiding sensitive data.
+
+1. **Enable Debug Logging**:
+   Configure your application\'s logger to output detailed debug messages when needed.
+   This often involves setting a log level via configuration.
+
+   ```javascript
+   // Example: Conceptual configuration
+   MyApp.configure({
+     logLevel: 'debug', // Or 'info', 'warn', 'error'
+     logFormatter: (severity, timestamp, message) => {
+       return `[${timestamp}] ${severity.toUpperCase()}: ${message}`;
+     }
+   });
+   ```
+
+2. **Inspect State**:
+   Provide mechanisms to inspect the internal state of key components during debugging, if feasible and safe.
+
+   ```javascript
+   // Example: Conceptual methods (actual implementation depends on language/design)
+   let debugInfo = agent.getDebugInfo();
+   let trace = agent.getExecutionTrace();
+   ```
+
+3. **Common Issues**:
+
+- LLM timeouts: Check network and retry settings
+- Memory issues: Review resource cleanup
+- Thread deadlocks: Check lock ordering
+
+## Error Context
+
+Always include relevant context when raising or logging errors. This aids debugging significantly.
+
+**Good Context:**
+
+```plaintext
+// Log the error with context
+logError(\"Failed to process user data\", error, { userId: 123, operation: \'updateProfile\' });
+
+// Raise error with context
+throw new UserProcessingError(\"Failed to update profile for user 123\", { originalError: error, userId: 123 });
+```
+
+**Avoid Generic Messages:**
+
+```plaintext
+// Less helpful
+logError("An error occurred", error);
+throw new Error("Something went wrong");
+```
+
+## Language/Environment-Specific Examples
+
+For specific code examples demonstrating error handling patterns, custom error classes, or library integrations
+in different languages (e.g., Ruby\'s `begin/rescue`, Python\'s `try/except`, JavaScript\'s `try/catch`,
+
+## Related Documentation
+
+- [Coding Standards](./coding-standards.g.md)
+- [Quality Assurance](./quality-assurance.g.md) (Logging, Monitoring)