Add debugging guidelines to AGENTS.md and copilot-instructions.md for improved test-driven development practices

Author: rsmithlal

.github/copilot-instructions.md

@@ -92,6 +92,19 @@ This repository contains the **Better Together Community Engine** (an isolated R
 
 ## Coding Guidelines
 
+### Debugging and Development Practices
+- **Never use Rails console or runner for debugging** - These commands don't support our test-driven development approach
+- **Debug through comprehensive tests**: Write detailed test scenarios to reproduce, understand, and verify fixes for issues
+- **Use test-driven debugging workflow**:
+  - Create specific tests that reproduce the problematic behavior
+  - Add debugging assertions in tests to verify intermediate state
+  - Trace through code by reading files and using grep search
+  - Validate fixes by ensuring tests pass
+- **Leverage RSpec debugging tools**: Use `--format documentation` for detailed output, `fit` for focused testing, `puts` for temporary debug output in tests
+- **Analyze logs and error messages**: Examine Rails logs, test output, and stack traces for debugging information
+- **Read code systematically**: Use file reading tools to understand code paths and data flow
+- **Temporary debug output**: Add debug statements in application code if needed, but remove before committing
+
 ### Docker Environment Usage
 - **All database-dependent commands must use `bin/dc-run`**: This includes tests, generators, and any command that connects to PostgreSQL, Redis, or Elasticsearch
 - **Dummy app commands use `bin/dc-run-dummy`**: For Rails commands that need the dummy app context (console, migrations specific to dummy app)
@@ -102,10 +115,11 @@ This repository contains the **Better Together Community Engine** (an isolated R
   - RuboCop: `bin/dc-run bundle exec rubocop`
   - **IMPORTANT**: Never use `rspec -v` - this displays version info, not verbose output. Use `--format documentation` for detailed output.
 - **Examples of commands requiring `bin/dc-run-dummy`**:
-  - Rails console: `bin/dc-run-dummy rails console`
+  - Rails console: `bin/dc-run-dummy rails console` (for administrative tasks only, NOT for debugging)
   - Dummy app migrations: `bin/dc-run-dummy rails db:migrate`
   - Dummy app database operations: `bin/dc-run-dummy rails db:seed`
 - **Commands that don't require bin/dc-run**: File operations, documentation generation (unless database access needed), static analysis tools that don't connect to services
+- **CRITICAL**: Rails console and runner are NOT debugging tools in this project - use comprehensive test suites instead
 
 ### Security Requirements
 - **Run Brakeman before generating code**: `bin/dc-run bundle exec brakeman --quiet --no-pager` 

AGENTS.md

@@ -19,6 +19,17 @@ Instructions for GitHub Copilot and other automated contributors working in this
   - test: `community_engine_test`
 - Use `DATABASE_URL` to connect (overrides fallback host in `config/database.yml`).
 
+## Debugging Guidelines
+- **Never use Rails console or runner for debugging** - These commands don't align with our test-driven development approach
+- **Use comprehensive test suites instead**: Write detailed tests to understand and verify system behavior
+- **Debug through tests**: Create specific test scenarios to reproduce and validate fixes for issues
+- **Use log analysis**: Examine Rails logs, test output, and error messages for debugging information
+- **Add temporary debugging assertions in tests**: Use `expect()` statements to verify intermediate state in tests
+- **Use RSpec debugging tools**: Use `--format documentation` for detailed test output, `fit` for focused testing
+- **Trace through code by reading files**: Use file reading and grep search to understand code paths
+- **Add debug output in application code temporarily** if needed, but remove before committing
+- **Validate fixes through test success**: Confirm that issues are resolved by having tests pass
+
 ## Commands
 - **Tests:** `bin/dc-run bin/ci`
   (Equivalent: `bin/dc-run bash -c "cd spec/dummy && bundle exec rspec"`)
@@ -29,7 +40,7 @@ Instructions for GitHub Copilot and other automated contributors working in this
   - Multiple specific lines: `bin/dc-run bundle exec rspec spec/file1_spec.rb:123 spec/file2_spec.rb:456`
   - **Important**: RSpec does NOT support hyphenated line numbers (e.g., `spec/file_spec.rb:123-456` is INVALID)
   - **Do NOT use `-v` flag**: The `-v` flag displays RSpec version information, NOT verbose output. Use `--format documentation` for detailed test descriptions.
-- **Rails Console:** `bin/dc-run-dummy rails console` (runs console in the dummy app context)
+- **Rails Console:** `bin/dc-run-dummy rails console` (for administrative tasks only - NOT for debugging. Use comprehensive tests for debugging instead)
 - **Rails Commands in Dummy App:** `bin/dc-run-dummy rails [command]` for any Rails commands that need the dummy app environment
 - **Lint:** `bin/dc-run bundle exec rubocop`
 - **Security:** `bin/dc-run bundle exec brakeman --quiet --no-pager` and `bin/dc-run bundle exec bundler-audit --update`