Issues Management Guide¶

Overview¶

This internal guide provides comprehensive documentation for managing project issues using a bidirectional synchronization system between GitHub and Markdown files. The system enables team members to manage issues either through GitHub's web interface or by editing Markdown files directly, with automatic synchronization between both formats.

Project Information¶

Project Name: Multi-Agent Trading MVP

Repository: Maricusco/multi-agent-trading

Team Members: - shakedmanes - Developer (Development, feature implementation, code) - of1r - DevOps Engineer (Infrastructure, monitoring, deployment, observability)

Development Milestones: 1. Phase 1: Foundation & Market Data - Establish modular structure and unified market data integration 2. Phase 2: Database & Validation - Persistent storage with signal validation pipeline 3. Phase 3: API & Services - REST API with service layer abstraction 4. Phase 4: Interfaces & Deployment - User interfaces and production deployment

Issue Classification System¶

Issue Types¶

Issues are categorized into three primary types:

Bug - Defects, errors, or unexpected behavior requiring fixes
Feature - New functionality or enhancements to existing features
Task - General work items, refactoring, documentation, or infrastructure tasks

Issue Status Workflow¶

Issues progress through the following status states:

Status	Description	Next Actions
Backlog	Issue is identified but not yet prioritized for work	Move to Todo when ready
Todo	Issue is prioritized and ready to be worked on	Assign to developer, move to In Progress
In Progress	Issue is actively being worked on	Complete work, move to In Review
In Review	Issue work is complete and awaiting review	Review and approve, move to Done
Done	Issue is completed and verified	Close issue

Label System¶

Labels provide classification of issues. The system uses two primary label categories:

1. Priority Labels¶

Priority labels indicate business importance:

P0-Critical - Critical; blocks everything; must be resolved immediately
P1-High - High priority; must have for MVP
P2-Medium - Medium priority; should have
P3-Low - Low priority; nice to have

2. Module/Area Labels¶

Module labels indicate which area of the system the issue affects:

agents - Agent-related work (analysts, researchers, managers, trader, risk)
orchestration - Workflow orchestration and graph management
data - Market data adapters, vendors, and tools
api - FastAPI endpoints and API layer
database - Database layer, models, and migrations
services - Business logic services
cli - Command line interface
config - Configuration and settings
infra - Infrastructure, Docker, deployment

Note: - Type (Bug, Feature, Task) is tracked separately in the Type field, not as labels - Status is tracked separately in the Status field, not as labels - Multiple module labels can be applied to an issue if it affects multiple areas

Workflow Management¶

Creating Issues¶

When creating a new issue, follow this systematic approach:

Verify Dependencies First: Identify prerequisite issues and record them in the Dependencies section before sizing or scheduling
Assign Status: Choose the appropriate status (Backlog, Todo, In Progress, In Review, or Done)
Assign Type: Categorize work type (Bug, Feature, or Task)
Assign Priority: Select priority level (P0-Critical, P1-High, P2-Medium, or P3-Low)
Assign Module/Area: Select one or more module labels indicating which area(s) the issue affects
Set Milestone: Assign to appropriate milestone if applicable
Assign Team Members: Assign to appropriate team members based on roles:
shakedmanes (Developer): Development work, feature implementation, code changes, API development, agent logic
of1r (DevOps Engineer): Infrastructure, monitoring, observability, deployment, Docker, CI/CD, error handling, metrics, health checks
Both: For issues requiring collaboration or affecting multiple areas
Include Size Info: Add size estimate in the issue description's "Estimated Time" section or title

Common Label Combinations¶

Typical label combinations for different scenarios:

Critical Feature:

Type: Feature
Labels: Priority: P0-Critical | Module: agents

Refactoring Task:

Type: Task
Labels: Priority: P1-High | Module: orchestration

Documentation Update:

Type: Task
Labels: Priority: P2-Medium | Module: config

Infrastructure Setup:

Type: Task
Labels: Priority: P0-Critical | Module: infra

Bug Fix:

Type: Bug
Labels: Priority: P1-High | Module: data

Bidirectional Synchronization¶

The synchronization system enables seamless workflow between GitHub's web interface and Markdown file editing.

Architecture¶

The system provides two synchronization directions:

GitHub → Markdown: Fetch all issues from GitHub and generate a markdown file
Markdown → GitHub: Update GitHub issues from markdown file edits

Prerequisites¶

Required: - Python 3.8 or higher - GitHub personal access token with repo scope (required for private repositories and Markdown → GitHub sync) - Access to the repository

Optional: - GitHub CLI (gh) for token management (recommended)

Note: This repository is private. All sync operations require authentication via GITHUB_TOKEN environment variable.

Synchronization Workflows¶

Fetching Issues from GitHub¶

To fetch all issues from GitHub and generate a markdown file:

python3 scripts/sync_issues.py --from-github --to-markdown docs/content/github_issues.md

This command: - Fetches all issues (open and closed) from GitHub - Fetches all milestones - Generates a markdown file with issues organized by milestone - Includes status, labels, assignees, and full issue descriptions

Authentication: - Required for private repositories: GITHUB_TOKEN environment variable must be set - Token must have repo scope for full access to private repositories - Set token: export GITHUB_TOKEN=$(gh auth token) or use a personal access token - Without token, requests will fail with 404/401 errors for private repositories

Updating GitHub from Markdown¶

To update GitHub issues from markdown file edits:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github

This command: - Parses the markdown file - Fetches milestones from GitHub for ID mapping - Updates each issue on GitHub (title, body, state, status, milestone, labels, assignees)

Required: GITHUB_TOKEN environment variable must be set for this operation.

Dry Run Mode¶

Preview changes without actually updating GitHub:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github --dry-run

This mode: - Shows what would be updated - Displays issue numbers and fields that would change - Does not make any actual changes to GitHub

Selective Updates¶

Update only specific issue numbers:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github --issues 15 16 17

Skip Closed Issues¶

Update only open issues:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github --skip-closed

Check Sync Status¶

Check if the markdown file is in sync with GitHub without making changes:

python3 scripts/sync_issues.py --check-sync docs/content/github_issues.md

This command: - Generates a temporary markdown file from GitHub - Compares it with the existing markdown file (ignoring the "Generated:" timestamp) - Exits with code 0 if in sync, 1 if out of sync

Automated Sync Mechanisms¶

To ensure github_issues.md stays synchronized with GitHub for all developers, the project includes several automated mechanisms:

Pre-commit Hook¶

A pre-commit hook automatically checks if github_issues.md is in sync with GitHub before allowing commits. If the file is out of sync, the commit is blocked with instructions on how to fix it.

How it works: - Runs automatically when you commit changes to docs/content/github_issues.md - Compares the markdown file with the current state of GitHub issues - Blocks the commit if out of sync, providing clear instructions

What to do if blocked: 1. Sync from GitHub: make sync-issues-from-github 2. Review the changes and commit again

Or if you intentionally edited the markdown file: 1. Sync to GitHub: make sync-issues-to-github 2. Then sync back: make sync-issues-from-github 3. Review and commit again

Note: The hook only runs when github_issues.md is being modified. If you're not changing that file, the hook is skipped.

Makefile Targets¶

The project provides convenient Makefile targets for issue synchronization:

Sync from GitHub to Markdown:

export GITHUB_TOKEN=$(gh auth token)  # Required for private repositories
make sync-issues-from-github

This fetches all issues from GitHub and updates the markdown file. GITHUB_TOKEN is required for private repositories.

Sync from Markdown to GitHub:

export GITHUB_TOKEN=$(gh auth token)  # Required
make sync-issues-to-github

This updates GitHub issues based on the markdown file. Requires GITHUB_TOKEN to be set.

Check Sync Status:

export GITHUB_TOKEN=$(gh auth token)  # Required for private repositories
make sync-issues-check

This checks if the markdown file is in sync with GitHub without making any changes. GITHUB_TOKEN is required for private repositories.

Preview Changes (Dry Run):

export GITHUB_TOKEN=$(gh auth token)  # Required
make sync-issues-dry-run

This shows what would be synced to GitHub without actually making changes.

Best Practices¶

Before committing changes to github_issues.md:
Run make sync-issues-check to verify sync status
If out of sync, run make sync-issues-from-github first
After editing issues on GitHub:
Run make sync-issues-from-github to update the markdown file
Commit the updated markdown file
After editing the markdown file:
Run make sync-issues-to-github to push changes to GitHub
Then run make sync-issues-from-github to ensure consistency
Review and commit
Regular maintenance:
Periodically run make sync-issues-check to verify sync status
Sync before starting work on issues to ensure you have the latest state

Synchronization Behavior¶

What Gets Synced:

Issue title
Issue body/description
Issue state (open/closed)
Status (tracked separately in Status field, not as labels)
Type (tracked separately in Type field, not as labels)
Milestone assignment
Labels (priority and module labels)
Assignees

What Doesn't Get Synced:

Comments (GitHub-only)
Reactions
Issue number (immutable)
Creation date (immutable)
GitHub-specific metadata

Important Notes:

Private Repository: This repository is private. All sync operations require GITHUB_TOKEN with repo scope
New issues created in markdown must first be created on GitHub via the web interface or API
The sync script updates existing issues only
Status is tracked separately in the Status field, not as labels
Type is tracked separately in the Type field, not as labels
Type labels are automatically removed from issues (type is not stored as labels)
Label names must exist on GitHub before they can be applied

Authentication Setup:

For private repositories, you must set up authentication:

# Using GitHub CLI (recommended)
export GITHUB_TOKEN=$(gh auth token)

# Or using a personal access token
export GITHUB_TOKEN=ghp_your_token_here

The token must have the repo scope to access private repositories and update issues.

Markdown Format Specification¶

Issue Structure¶

Each issue in the markdown file follows this structure:

### Issue #N: Issue Title

**State:** open|closed
**Status:** Backlog|Todo|In Progress|In Review|Done
**Type:** Bug|Feature|Task
**URL:** https://github.com/Maricusco/multi-agent-trading/issues/N
**Assignees:** username1, username2
**Labels:** Priority: P0-Critical | Module: agents
**Created:** YYYY-MM-DD
**Updated:** YYYY-MM-DD

---

## Description

Issue description content here...

## Why This Matters

- Reason 1
- Reason 2

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Subtasks

- [ ] Task 1
- [ ] Task 2

## Estimated Time

2-3 days

## Dependencies

- #5 Related Issue

---

Required Fields¶

Field	Description	Format	Required
`### Issue #N:`	Issue number and title	`### Issue #N: Title`	Yes
`State:`	Issue state	`open` or `closed`	Yes
`Status:`	Workflow status	`Backlog`, `Todo`, `In Progress`, `In Review`, or `Done`	No
`Type:`	Issue type	`Bug`, `Feature`, or `Task`	No
`URL:`	GitHub issue URL	Full URL or empty for new issues	Yes
`Assignees:`	Comma-separated usernames	`username1, username2` or `None`	Yes
`Labels:`	Grouped label format	See Label Format	No
`Created:`	Creation date	`YYYY-MM-DD`	Yes
`Updated:`	Last update date	`YYYY-MM-DD`	Yes

Label Format¶

Labels must be grouped by category and separated by pipe characters (|):

**Labels:** Priority: P0-Critical

Format Rules: - Categories separated by | - Multiple labels within a category separated by commas - Status is tracked separately in the Status field (not as labels) - Type is tracked separately in the Type field (not as labels) - Categories: Priority, Module

Examples:

Single priority label:

**Labels:** Priority: P1-High

Priority with module:

**Labels:** Priority: P0-Critical | Module: agents

Multiple modules:

**Labels:** Priority: P1-High | Module: data, api

Body Format¶

The issue body (description) must be enclosed between --- markers:

---

## Description

Detailed description of the issue...

## Why This Matters

- Business justification 1
- Business justification 2

## Acceptance Criteria

- [ ] Acceptance criterion 1
- [ ] Acceptance criterion 2

## Subtasks

- [ ] Subtask 1
- [ ] Subtask 2

## Estimated Time

1 day

## Dependencies

- #5 Related Issue
- #10 Another Issue

---

Formatting Rules: - Body must start and end with --- on separate lines - Use standard Markdown formatting - Preserve three blank lines between sections (as shown in examples) - Code blocks, lists, and tables are supported

Usage Guidelines¶

Adding a New Issue¶

To add a new issue to the markdown file:

Locate the appropriate milestone section (or "Issues Without Milestone")
Add the issue following the format specification:

### Issue #99: New Feature Implementation

**State:** open
**Status:** Todo
**Type:** Feature
**URL:** (will be created when synced to GitHub)
**Assignees:** shakedmanes
**Labels:** Priority: P1-High | Module: agents
**Created:** 2025-12-03
**Updated:** 2025-12-03

---

## Description

Detailed description of the new feature...

## Why This Matters

- Business value 1
- Business value 2

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Subtasks

- [ ] Subtask 1
- [ ] Subtask 2

## Estimated Time

1 day

## Dependencies

None

---

Create the issue on GitHub first (via web interface or API)
Sync to GitHub to update the issue:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github

Editing Existing Issues¶

To edit an existing issue:

Edit the issue in docs/content/github_issues.md
Review changes carefully
Use dry-run mode to preview changes:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github --dry-run

Sync to GitHub:

GITHUB_TOKEN=$(gh auth token) python3 scripts/sync_issues.py \
  --from-markdown docs/content/github_issues.md --to-github

Best Practices¶

Preserve Formatting: Maintain the three blank lines between sections as shown in examples
Use Proper Markdown: Code blocks, lists, tables, and other Markdown features work as expected
Review Before Syncing: Always review changes in the markdown file before syncing
Use Dry Run: Preview changes with --dry-run before making actual updates
Status Field: Use the **Status:** field to track workflow status (separate from state)
Label Consistency: Use consistent label names that match GitHub labels exactly
Date Format: Always use YYYY-MM-DD format for dates
Incremental Updates: Update specific issues using --issues flag when possible
Dependency Hygiene: Reconfirm and refresh dependencies before editing or syncing, especially when related issues change state

Troubleshooting¶

Parser Cannot Find Issues¶

Symptoms: Sync script reports "No issues found" or fails to parse issues.

Solutions: - Ensure issue format matches exactly, especially ### Issue #N: header - Verify that --- markers are present around the body section - Check for extra whitespace or formatting issues - Verify issue numbers are valid integers

Example of correct format:

### Issue #14: Title Here

**State:** open
...

Labels Not Parsing Correctly¶

Symptoms: Labels are not syncing to GitHub or appear incorrectly.

Solutions: - Use the grouped format: Priority: P0-Critical | Module: agents - Separate categories with | (pipe character) - Separate labels within a category with commas - Ensure label names match GitHub labels exactly (case-sensitive) - Verify labels exist on GitHub before using them - Type should be set in the Type field, not as labels

Correct format:

**Labels:** Priority: P0-Critical | Module: agents

Incorrect format:

**Labels:** P0-Critical, agents  # Missing category grouping
**Labels:** Priority: P0-Critical | Type: feature  # ❌ Type should be in Type field, not labels
**Type:** Feature  # ✅ Correct: Type is a separate field

Status Not Syncing¶

Symptoms: Status field changes are not reflected on GitHub.

Solutions: - Ensure status is in correct format: Backlog, Todo, In Progress, In Review, or Done - Status is case-insensitive and will be normalized automatically - Status is tracked separately in the Status field, not as labels - Status should not be included in the Labels field

Valid status values: - Backlog - Todo - In Progress (or InProgress) - In Review (or InReview) - Done

Sync Fails with Authentication Error¶

Symptoms: 401 Unauthorized or authentication errors.

Solutions: - Verify GITHUB_TOKEN environment variable is set correctly - Ensure token has appropriate permissions (repo scope) - Test token with: gh auth token or echo $GITHUB_TOKEN - For Markdown → GitHub sync, token is required - For GitHub → Markdown sync, token is optional but recommended

Sync Fails with "Label Not Found"¶

Symptoms: Error message indicates a label doesn't exist.

Solutions: - Create the label on GitHub first (via web interface or API) - Verify label name matches exactly (case-sensitive) - Check for typos in label names - Use label names: P0-Critical, P1-High, P2-Medium, P3-Low for priority - Type should be set in the Type field (Bug, Feature, or Task), not as labels

Issue Number Mismatch¶

Symptoms: Sync script cannot find issue on GitHub.

Solutions: - Verify issue number exists on GitHub - For new issues, create them on GitHub first before syncing - Check that issue number in markdown matches GitHub issue number - Use --issues flag to update specific issues only

Body Content Not Syncing¶

Symptoms: Issue body changes in markdown are not reflected on GitHub.

Solutions: - Ensure body is enclosed between --- markers - Verify body section starts after the **Updated:** field - Check for formatting issues in the body content - Use dry-run mode to verify what will be synced

Milestone Not Found¶

Symptoms: Milestone assignment fails during sync.

Solutions: - Verify milestone exists on GitHub - Ensure milestone title in markdown matches GitHub exactly - Check milestone state (closed milestones may not be assignable) - Use milestone title format: Phase N: Milestone Title (e.g., Phase 1: Foundation & Market Data)

Rate Limiting¶

Symptoms: API requests fail with rate limit errors.

Solutions: - Use authenticated requests (set GITHUB_TOKEN) - Reduce frequency of sync operations - Use --issues flag to update specific issues only - Wait for rate limit to reset (typically 1 hour)

Additional Resources¶

Sync Script: scripts/sync_issues.py
Generated Issues File: docs/content/github_issues.md
GitHub Repository: Maricusco/multi-agent-trading
GitHub Issues: View All Issues

Summary¶

This issues management system provides a flexible workflow for managing project issues through either GitHub's web interface or Markdown file editing. Bidirectional synchronization ensures consistency between both formats.

Key Benefits: - Edit issues in Markdown format - Version control for issue changes - Bulk editing capabilities - Consistent formatting and structure - Integration with existing GitHub workflow

Workflow Recommendations: 1. Use GitHub web interface for quick updates and comments 2. Use Markdown files for bulk edits and structured planning 3. Sync regularly to maintain consistency 4. Use dry-run mode before major updates 5. Follow the format specification strictly