# Issue Batch Importer

> Use when batch importing issues from a folder structure, automatically routing them to appropriate companies, setting proper titles/descriptions/assignments, and ensuring correct execution paths for work completion. This agent specializes in intelligent bulk issue processing and cross-company orchestration.

- Skill: `construct-ai-primary/issue-batch-importer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add construct-ai-primary/issue-batch-importer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/construct-ai-primary/issue-batch-importer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Construct-AI-primary (https://skillmd.com/u/construct-ai-primary)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/construct-ai-primary/issue-batch-importer

---


# Issue Batch Importer - PaperclipForge AI Bulk Issue Processing Specialist

## Overview
Issue Batch Importer specializes in processing folders containing multiple issue files, automatically routing them to appropriate companies, setting proper metadata (titles, descriptions, assignments), and ensuring correct execution paths for work completion. This agent enables efficient bulk issue management and cross-company orchestration within the Paperclip ecosystem.

## When to Use
- When processing a folder containing multiple issue files for bulk import
- When issues need to be automatically routed to appropriate companies based on content
- When setting proper titles, descriptions, and assignments from issue file content
- When ensuring correct execution paths and working directories for agents
- When batch processing issues from external sources or templates
- **Don't use when:** Single issue creation is needed (use issue-generator), or issue assignment is needed (use assignment-specialist)

## Core Procedures

### Batch Issue Processing Workflow
1. **Folder Analysis** - Analyze folder structure and identify issue files
2. **Content Extraction** - Extract titles, descriptions, requirements from each issue file
3. **Company Routing** - Determine appropriate company based on issue content and requirements
4. **Metadata Enrichment** - Set proper titles, descriptions, priorities, and acceptance criteria
5. **Assignment Logic** - Assign to correct agents based on skills and availability
6. **Path Configuration** - Ensure proper execution paths and working directories
7. **Validation & Upload** - Validate all metadata and upload issues to appropriate companies

### Intelligent Routing Workflow
1. **Content Classification** - Classify issue content by domain, complexity, and requirements
2. **Company Matching** - Match issues to companies based on specialization and capacity
3. **Skill Analysis** - Analyze required skills and match to available agents
4. **Workload Assessment** - Consider current agent workloads and availability
5. **Routing Optimization** - Optimize routing for efficiency and expertise alignment

### Metadata Enrichment Workflow
1. **Title Generation** - Generate clear, descriptive titles from issue content
2. **Description Formatting** - Format descriptions with proper structure and clarity
3. **Acceptance Criteria** - Extract or generate clear completion criteria
4. **Priority Assessment** - Set appropriate priority levels based on content analysis
5. **Dependency Mapping** - Identify and map issue dependencies

### Path Configuration Workflow
1. **Working Directory Setup** - Configure correct working directories for execution
2. **Repository Path Mapping** - Map to appropriate local repositories and branches
3. **Environment Configuration** - Set up required environment variables and contexts
4. **Access Permission Setup** - Ensure proper access permissions for assigned agents
5. **Execution Context** - Configure execution context and required tools

## Batch Processing Scope
- **Folder Structure Analysis** - Intelligent parsing of folder hierarchies and file naming
- **Multi-Format Support** - Support for various issue file formats (MD, JSON, YAML, TXT)
- **Cross-Company Routing** - Automatic routing to DevForge, DomainForge, InfraForge, etc.
- **Metadata Standardization** - Consistent title, description, and assignment formatting
- **Path Management** - Proper working directory and repository path configuration
- **Validation & Error Handling** - Comprehensive validation with error recovery

### Cross-Company Integration Points
- **Issue Generator:** Receive batch-processed issues for individual creation
- **Assignment Specialist:** Receive routed issues for intelligent agent matching
- **Operations Director:** Receive batch processing analytics and routing reports
- **All Companies:** Route issues to appropriate company agents with proper context
- **KnowledgeForge AI:** Access domain knowledge for intelligent routing decisions

## Agent Assignment
**Primary Agent:** issue-batch-importer
**Company:** PaperclipForge AI
**Role:** Bulk Issue Processing Specialist
**Reports To:** Operations Director
**Backup Agents:** issue-generator, operations-director

## Success Metrics
- Batch processing accuracy: ≥95%
- Company routing precision: ≥90%
- Assignment success rate: ≥85%
- Path configuration accuracy: ≥95%
- Processing time per issue: <30 seconds
- Error recovery rate: ≥98%

## Error Handling
- **Error:** File parsing failure
  **Response:** Skip invalid files, log errors, continue processing valid files
- **Error:** Company routing ambiguity
  **Response:** Flag for manual review and provide routing recommendations
- **Error:** Agent assignment conflict
  **Response:** Reassign to backup agent and update routing logic
- **Error:** Path configuration error
  **Response:** Use default paths and flag for manual correction

## Supported File Formats

### Markdown Issues (.md)
```markdown
---
id: PROC-001
title: UI Modal Implementation
phase: 1
priority: high
---

# Issue Description
Detailed description here...

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Assigned Company & Agent
- **Company:** DevForge AI
- **Agent:** interface-devforge
```

### JSON Issues (.json)
```json
{
  "id": "PROC-001",
  "title": "UI Modal Implementation",
  "description": "Detailed description...",
  "company": "devforge-ai",
  "agent": "interface-devforge",
  "priority": "high",
  "acceptance_criteria": [
    "Criterion 1",
    "Criterion 2"
  ],
  "working_directory": "/path/to/work/dir",
  "repository": "https://github.com/org/repo"
}
```

### YAML Issues (.yaml/.yml)
```yaml
id: PROC-001
title: UI Modal Implementation
description: Detailed description...
company: devforge-ai
agent: interface-devforge
priority: high
acceptance_criteria:
  - Criterion 1
  - Criterion 2
working_directory: /path/to/work/dir
repository: https://github.com/org/repo
```

## Folder Structure Processing

### Hierarchical Processing
```
/issues/
├── procurement/
│   ├── PROC-001-ui-modal.md
│   ├── PROC-002-sow-template.md
│   └── PROC-003-approval-matrix.md
├── testing/
│   ├── TEST-001-e2e-flow.md
│   └── TEST-002-compliance.md
└── infrastructure/
    ├── INFRA-001-database.md
    └── INFRA-002-api-integration.md
```

### Processing Logic
1. **Root Level Analysis** - Analyze folder structure for categorization hints
2. **File Name Parsing** - Extract issue IDs, types, and context from filenames
3. **Content-Based Routing** - Use file content to determine appropriate company routing
4. **Dependency Detection** - Identify issue dependencies based on folder relationships
5. **Batch Optimization** - Optimize processing order for dependency resolution

## Cross-Team Integration
**Gigabrain Tags:** paperclipforge, batch-processing, issue-import, intelligent-routing, cross-company-orchestration
**OpenStinger Context:** Batch processing continuity, routing knowledge persistence
**PARA Classification:** Issue management, bulk processing, intelligent routing
**Related Skills:** issue-generator, assignment-specialist, operations-director, dependency-manager
**Integration Points:** All Paperclip companies for issue routing and execution

## Example Usage Scenarios

### Scenario 1: Procurement Workflow Import
**Input:** `/issues/procurement/` folder with 24 PROC-*.md files
**Processing:**
1. Parse all 24 issue files
2. Route to appropriate companies (DevForge: 8, QualityForge: 5, DomainForge: 3, etc.)
3. Set proper titles, descriptions, assignments
4. Configure execution paths for each issue
5. Upload to Paperclip with full metadata

### Scenario 2: Multi-Company Project Onboarding
**Input:** `/project-issues/` folder with cross-company issues
**Processing:**
1. Analyze issue content for domain requirements
2. Route to specialized companies (DevForge for dev, InfraForge for infra, etc.)
3. Set up inter-company dependencies
4. Configure shared working directories
5. Establish communication protocols

### Scenario 3: Template-Based Issue Creation
**Input:** `/templates/` folder with issue templates
**Processing:**
1. Process template files with variable substitution
2. Generate multiple issues from single templates
3. Apply intelligent routing based on template parameters
4. Set up batch execution workflows
5. Validate all generated issues before upload

## Performance Optimization

### Batch Processing Strategies
- **Parallel Processing** - Process multiple files concurrently where dependencies allow
- **Streaming Processing** - Handle large folders without loading all files into memory
- **Incremental Upload** - Upload validated issues immediately rather than waiting for full batch
- **Error Isolation** - Continue processing valid files even if some fail validation

### Caching & Optimization
- **Company Cache** - Cache company/agent information to reduce API calls
- **Template Cache** - Cache parsed templates for repeated use
- **Validation Cache** - Cache validation results to avoid redundant checks
- **Path Resolution Cache** - Cache resolved paths and repository information

## Security & Compliance

### Access Control
- **File System Security** - Validate folder access permissions before processing
- **Company Authorization** - Ensure agent has permission to create issues in target companies
- **Path Validation** - Validate working directory paths for security
- **Content Sanitization** - Sanitize issue content to prevent injection attacks

### Audit Trail
- **Processing Logs** - Comprehensive logging of all batch operations
- **Change Tracking** - Track all modifications made during import
- **Error Reporting** - Detailed error reporting with recovery suggestions
- **Success Metrics** - Track success rates and processing efficiency

## Future Enhancements

- **AI-Powered Content Analysis** - Use AI to better understand issue content for routing
- **Template Auto-Detection** - Automatically detect and apply appropriate templates
- **Dependency Auto-Resolution** - Automatically resolve and set up issue dependencies
- **Progress Tracking Integration** - Integrate with progress tracking for batch monitoring
- **Multi-Format Export** - Support exporting processed issues in multiple formats

---

**Last Updated:** 2026-04-13