# Issue Roadmap System

## Overview

The Issue Roadmap System is a systematic approach to analyzing, tracking, and resolving test failures in the mcp-abap-adt project. It provides a structured workflow for problem identification, root cause analysis, solution development, and progress tracking.

## Purpose

The system was introduced to:
- **Systematically analyze test failures** instead of ad-hoc debugging
- **Document solutions** for future reference and knowledge sharing
- **Track progress** on fixing issues vs expected skips vs cloud limitations
- **Prevent duplicate work** by maintaining a history of resolved issues
- **Provide context** for similar problems encountered in the future

## File Structure

Issue roadmaps are stored in `docs/development/roadmaps/archive/` directory with naming pattern:
```
TEST_ISSUES_ROADMAP_YYYY-MM-DD.md
```

Example: `TEST_ISSUES_ROADMAP_2025-11-27.md` (archived)

## Workflow

### 1. Test Run and Log Collection

When tests fail, run with debug logging enabled:
```bash
DEBUG_TESTS=true npm test 2>&1 | tee /tmp/test-debug-$(date +%Y-%m-%d_%H-%M-%S).log
```

Store logs outside git repository (in `/tmp/` or similar).

### 2. Issue Analysis

For each test failure:
1. **Extract error message** from test output
2. **Identify test file** and specific test case
3. **Check YAML configuration** for test parameters
4. **Review handler code** to understand the flow
5. **Classify the issue** (Simple vs Complex, Real Issue vs Expected Skip)

### 3. Issue Classification

#### Simple Issues (⚡)
- Quick fixes requiring no deep analysis
- Missing parameters
- Code bugs (wrong parameter passing, missing checks)
- Configuration issues

#### Complex Issues (🔍)
- Require investigation and analysis
- Parameters are correct but operation fails
- Unexpected behavior despite correct input
- Need to analyze response data, dependencies, or system state

#### Expected Skips (⏭️)
- Cloud system limitations (e.g., Programs not available on cloud)
- Missing dependencies (e.g., Behavior Definition doesn't exist)
- Disabled test cases (enabled: false in YAML)
- Known SAP API quirks that are acceptable

### 4. Issue Documentation

Each issue in the roadmap includes:

#### Issue Header
- **Issue number** (sequential: #1, #2, #3...)
- **Title** (descriptive, includes object type and handler level)
- **Status** (✅ Fixed, 🔴 Pending, ⏭️ Expected)
- **Type** (⚡ Simple or 🔍 Complex)
- **Category** (Validation, Parameter, Object State, etc.)

#### Issue Details
- **Test File** path
- **YAML Config** section and test case name
- **Error message** (snippet from logs)
- **Problem description** (what's happening and why)
- **Root cause analysis** (for complex issues)
- **Solution approach** (how it was/will be fixed)
- **Code references** (file paths and line numbers)
- **Test result** (current status)

### 5. Solution Implementation

When fixing an issue:
1. **Implement the fix** in code
2. **Update test configuration** if needed (YAML)
3. **Run tests** to verify the fix
4. **Update roadmap** with fix details
5. **Update statistics** (Fixed count, Pending count)

### 6. Progress Tracking

The roadmap maintains statistics:
- **Total Issues** (original + new)
- **Fixed** (✅) - resolved issues
- **Pending** (🔴) - issues needing attention
- **Skipped/Expected** (⏭️) - expected behavior, not real issues

## Roadmap Structure

### Summary Section
- Overview statistics
- Issues summary table with links
- Legend explaining status symbols

### Issues by Object Type
- Grouped by object type (Function, Domain, Package, etc.)
- Each issue has detailed analysis

### Analysis Priority
- Simple issues listed first (quick fixes)
- Complex issues with detailed analysis
- Expected skips documented separately

### Progress Tracking
- Historical record of fixes
- Test results with dates
- Links to test logs

## Best Practices

### When Creating a New Roadmap Entry

1. **Be specific** - Include exact error messages, file paths, line numbers
2. **Provide context** - Explain what the test is trying to do
3. **Document root cause** - Not just symptoms, but why it's happening
4. **Include code references** - Use proper code reference format:
   ```markdown
   ```startLine:endLine:filepath
   // code content
   ```
   ```
5. **Update status** - Keep status current as work progresses

### When Fixing Issues

1. **Update roadmap first** - Document the fix approach
2. **Implement fix** - Make code changes
3. **Verify fix** - Run tests to confirm
4. **Update roadmap** - Mark as fixed, add solution details
5. **Update statistics** - Increment fixed count

### When Analyzing Issues

1. **Don't assume** - Verify by checking code and logs
2. **Check dependencies** - Ensure required objects exist
3. **Review similar issues** - Check if this was fixed before
4. **Consider system limitations** - Cloud vs on-premise differences
5. **Document findings** - Even if it's an expected skip

## Integration with Development Workflow

The Issue Roadmap System is integrated into the development cycle:

1. **Test failures** → Analyze and document in roadmap
2. **Fix issues** → Update roadmap with solution
3. **Release** → Roadmap changes included in changelog
4. **Knowledge base** → Roadmap serves as historical reference

## Benefits

- **Faster problem resolution** - Structured approach reduces debugging time
- **Knowledge preservation** - Solutions documented for future reference
- **Progress visibility** - Clear view of test suite health
- **Prevents regression** - Historical context helps avoid similar issues
- **Team collaboration** - Shared understanding of problems and solutions

## Example Workflow

1. Test fails: `DomainHighHandlers - Update failed: Domain already exists`
2. Analyze: Check handler code, builder logic, test configuration
3. Classify: Complex issue - workflow detection problem
4. Document: Add to roadmap as Issue #10 with full analysis
5. Fix: Pass `packageName` to `lockDomain()`, remove validation
6. Verify: Run tests, confirm fix works
7. Update: Mark Issue #10 as Fixed, update statistics
8. Release: Include fix in changelog

## Maintenance

- **Update after each test run** - Keep roadmap current
- **Review periodically** - Ensure pending issues are being addressed
- **Clean up** - Remove resolved issues from active tracking if needed

## Related Documentation

- `CHANGELOG.md` - Release notes including roadmap updates
- `BUILDER_TEST_PATTERN.md` - Test writing patterns
- `TEST_CONFIG_SCHEMA.md` - Test configuration structure