Complete User Guide

# From repository root
pip install -e reverse-engineer-python/

# Or if published to PyPI
pip install re-cue

recue --version
recue --help

# .github/workflows/docs.yml
name: Documentation
on: [push, pull_request]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: cue-3/re-cue/.github/actions/re-cue@v1
        with:
          generate-all: true
          commit-changes: true

git clone https://github.com/cue-3/re-cue.git
cd re-cue
./install.sh ~/projects/my-app

# Interactive mode (prompts for options)
recue

# Generate specific documentation types
recue --spec                    # Feature specification only
recue --plan                    # Implementation plan only
recue --data-model              # Data model only
recue --api-contract            # API contract only
recue --use-cases               # Use cases only

# Generate multiple types
recue --spec --plan --data-model

# Generate everything
recue --spec --plan --data-model --api-contract --use-cases

# Specify project path
recue --spec --path ~/projects/my-app

# Add description
recue --spec --description "E-commerce platform"

# Verbose output
recue --spec --verbose

# Custom output directory
recue --spec --output docs/specs/

# Specify output format (markdown or json)
recue --spec --format json

# Phased analysis (for large codebases)
recue --use-cases --phased --path ~/projects/large-app

# Specify framework manually
recue --spec --framework java_spring --path ~/projects/my-app

# Interactive use case refinement
recue --refine-use-cases re-my-app/phase4-use-cases.md

# Resume from specific phase
recue --use-cases --phased --resume-from 3

# Navigate to your project
cd ~/projects/my-app

# Generate specific documentation
./.github/scripts/reverse-engineer.sh --spec
./.github/scripts/reverse-engineer.sh --plan
./.github/scripts/reverse-engineer.sh --data-model
./.github/scripts/reverse-engineer.sh --api-contract

# Generate multiple types
./.github/scripts/reverse-engineer.sh --spec --plan --data-model --api-contract

# Verbose mode
./.github/scripts/reverse-engineer.sh --spec --verbose

recue --spec --description "User management system"

# Feature Specification: User Management System

## Executive Summary
This system provides comprehensive user account management including
registration, authentication, profile management, and role-based access control.

## User Stories

### US-001: User Registration
**As a** new visitor
**I want to** create an account with email and password
**So that** I can access protected features

**Acceptance Criteria:**
- Email validation follows RFC 5322 standard
- Password must be at least 8 characters
- Confirmation email sent within 5 seconds
- Account created with default 'USER' role
...

recue --plan --description "User management system"

# Implementation Plan: User Management System

## Architecture Overview
Layered architecture following Spring Boot best practices:
- REST API Layer (Controllers)
- Service Layer (Business Logic)
- Data Access Layer (Repositories)
- Domain Model (Entities)

## Components

### UserController
**Responsibility**: HTTP request handling for user operations
**Endpoints**:
- POST /api/users - Create new user
- GET /api/users/{id} - Retrieve user details
- PUT /api/users/{id} - Update user information
- DELETE /api/users/{id} - Delete user account
...

recue --data-model --description "User management system"

# Data Model: User Management System

## Entities

### User
**Description**: Represents a system user account

**Fields**:
| Field | Type | Required | Validation | Description |
|-------|------|----------|------------|-------------|
| id | Long | Yes | Auto-generated | Primary key |
| email | String | Yes | Email format, Unique | User's email address |
| password | String | Yes | Min 8 chars | Encrypted password |
| firstName | String | Yes | 2-50 chars | User's first name |
| lastName | String | Yes | 2-50 chars | User's last name |
| roles | Set<Role> | Yes | Not empty | User's access roles |
| createdAt | Timestamp | Yes | Auto-set | Account creation time |
| updatedAt | Timestamp | Yes | Auto-update | Last modification time |

**Relationships**:
- Many-to-Many with Role (through user_roles join table)
- One-to-Many with Order (as customer)
...

recue --api-contract --description "User management API"

{
  "openapi": "3.0.0",
  "info": {
    "title": "User Management API",
    "version": "1.0.0",
    "description": "API for managing user accounts"
  },
  "paths": {
    "/api/users": {
      "post": {
        "summary": "Create new user",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}

recue --use-cases --description "User management system"

# Use Case Analysis: User Management System

## Actors

### Primary Actors
- **Customer** - End user accessing the system
- **Administrator** - System administrator with elevated privileges

### Secondary Actors
- **Email Service** - External system for sending emails
- **Payment Gateway** - External payment processing

## System Boundaries

### Customer Portal
- User registration and login
- Profile management
- Order placement

### Admin Console
- User management
- System configuration
- Reporting

## Use Cases

### UC-001: Register New User Account

**Primary Actor**: Customer
**System Boundary**: Customer Portal
**Goal**: Create a new user account to access the system

#### Business Context
- **Transaction Boundaries**: 2
- **Validation Rules**: 5
- **Workflow Patterns**: 1
- **Business Rules**: 8

#### Preconditions
- User must not already have an account
- Email address must be valid and not in use
- All required fields must be provided

#### Main Success Scenario
1. Customer navigates to registration page
2. Customer enters email, password, first name, and last name
3. System validates input fields
4. System checks email availability
5. System creates user account with default role
6. System sends confirmation email
7. System displays success message

#### Postconditions
- User account created in database
- Confirmation email queued for delivery
- User can log in with credentials

#### Extensions
**3a**: Validation fails
  - 3a1: System displays field-specific error messages
  - 3a2: Customer corrects errors
  - 3a3: Resume at step 3

**4a**: Email already registered
  - 4a1: System displays "Email already in use" message
  - 4a2: System suggests password reset
  - 4a3: Use case ends

**6a**: Email service unavailable
  - 6a1: System logs error
  - 6a2: System queues email for retry
  - 6a3: Continue to step 7
...

# Override automatic detection
recue --spec --framework java_spring
recue --spec --framework ruby_rails
recue --spec --framework nodejs_express

recue --use-cases --path ~/projects/spring-boot-app --verbose

recue --use-cases --phased --path ~/projects/large-app

# Resume from phase 3 after interruption
recue --use-cases --phased --resume-from 3

recue --refine-use-cases re-my-app/phase4-use-cases.md

$ recue --refine-use-cases re-my-app/phase4-use-cases.md

📝 Use Case Refinement Tool
Type 'help' for available commands

> list
Found 12 use cases:
  UC-001: Register User Account
  UC-002: User Login
  UC-003: Reset Password
  ...

> view UC-001
UC-001: Register User Account
Primary Actor: Customer
System Boundary: Customer Portal
...

> edit UC-001
# Opens your default editor for editing

> save
✓ Changes saved to re-my-app/phase4-use-cases.md

> quit

# Edit templates to match your organization's standards
vim reverse-engineer-python/reverse_engineer/templates/phase4-use-cases.md

# Set worker count to 1
export RECUE_WORKERS=1
recue --use-cases

# Morning: Check what changed
git diff main --name-only

# Regenerate docs for changed modules
cd backend/user-service
recue --spec --plan --data-model

# Review and commit
git add re-user-service/
git commit -m "docs: Update user service documentation"

# 1. Analyze current state
recue --spec --use-cases --description "Current order system"

# 2. Review generated docs
cat re-myapp/spec.md
cat re-myapp/phase4-use-cases.md

# 3. Identify components to modify
grep -r "Order" re-myapp/

# 4. Begin development with understanding

# 1. Update documentation
recue --spec --plan --api-contract

# 2. Review changes
diff old-docs/ new-docs/

# 3. Commit alongside code changes
git add src/ re-myapp/
git commit -m "feat: Add order cancellation feature"

# .github/workflows/docs.yml
name: Documentation Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    types: [opened, synchronize]

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Generate Documentation
        uses: cue-3/re-cue/.github/actions/re-cue@v1
        with:
          generate-all: true
          commit-changes: false
      
      - name: Check for Documentation Changes
        id: docs-check
        run: |
          if git diff --quiet re-*/; then
            echo "No documentation changes"
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "Documentation needs updating"
            echo "changed=true" >> $GITHUB_OUTPUT
          fi
      
      - name: Comment on PR
        if: github.event_name == 'pull_request' && steps.docs-check.outputs.changed == 'true'
        uses: actions/github-script@v6
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '⚠️ Documentation may need updating. Please run `recue --spec --plan` and commit changes.'
            })
      
      - name: Upload Documentation
        uses: actions/upload-artifact@v3
        with:
          name: documentation
          path: re-*/
          retention-days: 30

# .github/workflows/validate-docs.yml
name: Validate Documentation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Generate Fresh Documentation
        uses: cue-3/re-cue/.github/actions/re-cue@v1
        with:
          generate-all: true
      
      - name: Compare with Committed Docs
        run: |
          if ! diff -r re-myapp/ committed-docs/; then
            echo "❌ Documentation is out of date"
            echo "Run 'recue --spec --plan --api-contract' locally and commit changes"
            exit 1
          fi
          echo "✅ Documentation is up to date"

# .git/hooks/pre-commit
#!/bin/bash

# Check if source files changed
if git diff --cached --name-only | grep -q "src/"; then
  echo "Source files changed, checking documentation..."
  
  # Regenerate docs
  recue --spec --plan --quiet
  
  # Stage updated docs
  git add re-*/
  
  echo "Documentation updated and staged"
fi

# .git/hooks/post-merge
#!/bin/bash

echo "Updating documentation after merge..."
recue --spec --plan --data-model
echo "Documentation regenerated"

# Use phased analysis
recue --use-cases --phased

# Increase parallelization
export RECUE_WORKERS=8
recue --use-cases --phased

# Focus on specific directories
recue --spec --path ~/projects/myapp/src/main/java/com/company/core

# Use phased mode to cache intermediate results
recue --use-cases --phased

# Subsequent runs will be 5-6x faster
recue --use-cases --phased

# Ensure security annotations are present
# Add @PreAuthorize, @Secured, or @RolesAllowed to controllers

# Add transaction annotations
# Use @Transactional with propagation and isolation levels

# Add validation annotations
# Use @NotNull, @Size, @Email, @Pattern on entity fields

# Add workflow annotations
# Use @Async, @Scheduled, @Retryable on service methods

# Add OpenAPI annotations (Swagger)
# Use @Operation, @ApiResponse, @Schema annotations

# Or use comprehensive documentation comments
/**
 * Creates a new user account
 * @param request User registration details
 * @return Created user with assigned ID
 * @throws ValidationException if input is invalid
 */

# Limit file processing
export RECUE_MAX_FILES=500
recue --use-cases

# Reduce parallel workers
export RECUE_WORKERS=2
recue --use-cases

# Use phased analysis
recue --use-cases --phased

# Solution 1: Verify framework detection
grep -r "@RestController\|@Controller" src/

# Solution 2: Specify framework manually
recue --spec --framework java_spring

# Solution 3: Check project structure
ls -la src/main/java/

# Solution 1: Use phased mode
recue --use-cases --phased

# Solution 2: Limit scope
recue --spec --path src/main/java/com/company/core

# Solution 3: Increase parallelization
export RECUE_WORKERS=8
recue --use-cases

# Solution: Add security annotations
# Check for @PreAuthorize, @Secured, @RolesAllowed
grep -r "@PreAuthorize\|@Secured" src/

# If none found, add to your controllers:
@PreAuthorize("hasRole('ADMIN')")
public ResponseEntity<User> deleteUser(@PathVariable Long id) {
    // ...
}

# Solution: Add annotations for business context
# 1. Add @Transactional for transaction boundaries
# 2. Add @NotNull, @Size, etc. for validation rules
# 3. Add @Async, @Scheduled for workflow patterns

grep -r "@Transactional\|@NotNull\|@Valid\|@Async" src/

# Solution: Reinstall in editable mode
cd reverse-engineer-python
pip install -e .

# Verify installation
pip list | grep reverse-engineer

# Solution: Check file permissions
chmod +x .github/scripts/reverse-engineer.sh

# Or run with bash explicitly
bash .github/scripts/reverse-engineer.sh --spec