Version: 3.0.1

Change Detection Guide

How to identify what changed between versions and produce a Change Manifest.

Sources of Change

Source	Location	What to Look For
PRD/Specs	`input/`	New features, modified behaviors
Ideas/Instructions	`input/`	Enhancement requests, fixes
Confluence Exports	`input/`	New requirements in Word (.docx) — run through conversion pipeline
Code Changes	Git history	Implementation changes
Test Changes	`tests/`	New/modified test cases
Stakeholder Input	External	Change requests, bug reports

Step 1: Review PRD/Specification Changes

# List all input documents
ls -la input/

# Check for new or modified spec files
git diff v{OLD}..HEAD -- input/

# Read the authoritative spec
cat input/phase0\ specs.md

Look for:

New feature descriptions
Modified behavior specifications
Deprecated or removed functionality
New configuration options
Security or compliance changes

Step 1b: Convert Confluence Exports (If Applicable)

If the new version includes requirements documented in Confluence that haven't been converted to SRS format:

Check input/ for new .docx files from Confluence exports

Convert to AsciiDoc (preserves table structure that Markdown breaks):

docusaurus/scripts/docx2adoc.sh input/new-export.docx output/new-export.adoc

Follow the full 6-stage pipeline in the SRS Confluence Conversion Guide:
- Source Analysis → Classification → Transformation → Validation
The conversion output feeds into the Change Manifest as NEW requirements

Why AsciiDoc? Confluence exports contain complex tables with merged cells and nested content. Pandoc's AsciiDoc writer preserves this structure; the Markdown writer collapses it, making programmatic reconstruction difficult.

Skip this step if all version changes come from code diffs and existing structured documentation.

Step 2: Analyze Code Changes

High-Level Overview

# Overall change stats
git diff v{OLD}..v{NEW} --stat

# Commit count
git log v{OLD}..v{NEW} --oneline | wc -l

# Commit summary (grouped by file)
git log v{OLD}..v{NEW} --name-status --pretty=format:"%s" | head -100

Backend Changes (PHP/Laravel)

# All backend changes
git diff v{OLD}..v{NEW} -- app/

# Controllers (entry points)
git diff v{OLD}..v{NEW} -- app/Http/Controllers/

# Services (business logic)
git diff v{OLD}..v{NEW} -- app/Services/

# Models (data layer)
git diff v{OLD}..v{NEW} -- app/Models/ app/*.php

# Jobs (async processing)
git diff v{OLD}..v{NEW} -- app/Jobs/

# Events (integrations)
git diff v{OLD}..v{NEW} -- app/Events/

# Migrations (schema changes)
git diff v{OLD}..v{NEW} -- database/migrations/

Frontend Changes (Vue/TypeScript)

# All frontend changes
git diff v{OLD}..v{NEW} -- resources/js/

# Page components
git diff v{OLD}..v{NEW} -- resources/js/Pages/

# Feature components
git diff v{OLD}..v{NEW} -- resources/js/Components/

# Composables (state/logic)
git diff v{OLD}..v{NEW} -- resources/js/Composables/

Configuration Changes

# Environment config
git diff v{OLD}..v{NEW} -- config/

# Routes
git diff v{OLD}..v{NEW} -- routes/

Step 3: Review Test Changes

Identify changes to the test suite that may require STD documentation updates.

# Behat API test scenarios
git diff v{OLD}..v{NEW} -- tests/exports/

# Behat browser test scenarios
git diff v{OLD}..v{NEW} -- tests/exports/browser/

# Test fixtures and support files
git diff v{OLD}..v{NEW} -- tests/support_files/

# Unit / Feature tests (Laravel PHPUnit)
git diff v{OLD}..v{NEW} -- tests/Unit/ tests/Feature/

For each changed test area:

Update STD specs -- If requirements changed, update the corresponding docusaurus/docs/std/ file (add/modify test vectors, update acceptance criteria mappings)
Map new TVs -- New test vectors need @TV-RULE-NNN-NNN or @TC-DOMAIN-NNN-ACNN tags in Behat feature files
Create or update Behat scenarios -- New requirements need test scenarios; modified requirements may need updated assertions or fixtures
Verify TV tag coverage -- Run the unified traceability script to confirm all new TVs are mapped to test files:
```
python3 docusaurus/scripts/generate-unified-traceability.py --validate
```

Run affected Behat suites -- Execute tests for any modified feature files to confirm they pass:

DB_HOST=127.0.0.1 DB_AUDIT_HOST=127.0.0.1 DB_DATABASE=pcrai_test_01 \
  DB_USERNAME=sail DB_PASSWORD=password \
  vendor/bin/behat --suite=v3 --tags="@BT-XXXX"

Step 4: Categorize Changes

For each change identified, categorize as:

Type	Code	Description
NEW	`NEW`	New feature or capability
MODIFIED	`MOD`	Changed existing behavior
DEPRECATED	`DEP`	Marked for removal (still works)
REMOVED	`REM`	Functionality deleted
FIX	`FIX`	Bug fix (may affect docs)
REFACTOR	`REF`	Code change, no behavior change

Step 5: Create Change Manifest

Template

# Change Manifest: v{OLD} → v{NEW}

**Generated:** YYYY-MM-DD
**Author:** [Name or LLM Session]

## Summary

| Type | Count |
|------|-------|
| NEW | X |
| MOD | X |
| DEP | X |
| REM | X |
| FIX | X |

## Changes

### NEW Features

| ID | Description | Source | Affected SRS | Affected SDS |
|----|-------------|--------|--------------|--------------|
| CHG-001 | New export format | PRD | fileimport.md | sds-domain-fileimport.md |
| CHG-002 | Dashboard widget | Code | runfile-list.md | sds-domain-runfile.md |

### MODIFIED Behaviors

| ID | Description | Source | Affected SRS | Affected SDS |
|----|-------------|--------|--------------|--------------|
| CHG-010 | Auth flow timeout | Code | user-management.md | sds-05-security-architecture.md |

### DEPRECATED Features

| ID | Description | Source | Affected SRS | Affected SDS | Target Removal |
|----|-------------|--------|--------------|--------------|----------------|
| CHG-020 | Legacy API v1 | Decision | client-config.md | sds-ref-api.md | v3.2 |

### REMOVED Features

| ID | Description | Source | Affected SRS | Affected SDS |
|----|-------------|--------|--------------|--------------|
| CHG-030 | Old report format | Decision | reports.md | sds-domain-reports.md |

### BUG FIXES (Doc-Relevant)

| ID | Description | Source | Affected SRS | Notes |
|----|-------------|--------|--------------|-------|
| CHG-040 | Validation edge case | Code | kitcfg.md | AC clarification |

## Cross-Cutting Concerns

- [ ] Security impact: [Yes/No] - Details
- [ ] Audit logging changes: [Yes/No] - Details
- [ ] Configuration changes: [Yes/No] - Details
- [ ] API changes: [Yes/No] - Details

## Notes

- Any special considerations
- Dependencies between changes
- Rollback considerations

Automation Scripts

Generate Change Summary

#!/bin/bash
# change-summary.sh - Generate change summary between versions

OLD_VERSION=$1
NEW_VERSION=$2

echo "# Change Summary: $OLD_VERSION → $NEW_VERSION"
echo ""
echo "## Commit Statistics"
git log $OLD_VERSION..$NEW_VERSION --oneline | wc -l | xargs echo "Total commits:"

echo ""
echo "## File Changes by Area"
echo "### Backend (app/)"
git diff $OLD_VERSION..$NEW_VERSION --stat -- app/ | tail -1

echo "### Frontend (resources/js/)"
git diff $OLD_VERSION..$NEW_VERSION --stat -- resources/js/ | tail -1

echo "### Migrations"
git diff $OLD_VERSION..$NEW_VERSION --stat -- database/migrations/ | tail -1

echo "### Config"
git diff $OLD_VERSION..$NEW_VERSION --stat -- config/ | tail -1

echo ""
echo "## New Files"
git diff $OLD_VERSION..$NEW_VERSION --name-status | grep "^A" | head -20

echo ""
echo "## Deleted Files"
git diff $OLD_VERSION..$NEW_VERSION --name-status | grep "^D" | head -20

Find REQ References in Changed Files

#!/bin/bash
# find-affected-reqs.sh - Find REQ references in changed files

OLD_VERSION=$1
NEW_VERSION=$2

echo "# Potentially Affected Requirements"
echo ""

# Get changed files
CHANGED_FILES=$(git diff $OLD_VERSION..$NEW_VERSION --name-only -- app/ resources/js/)

for file in $CHANGED_FILES; do
  # Check if file exists (not deleted)
  if [ -f "$file" ]; then
    REQS=$(grep -oh "REQ-[A-Z]*-[0-9]*" "$file" 2>/dev/null | sort -u)
    if [ -n "$REQS" ]; then
      echo "## $file"
      echo "$REQS"
      echo ""
    fi
  fi
done

Inventory Extraction (From Pass B Patterns)

When significant changes occur, extract bounded inventories to understand the full scope.

Reference: These patterns come from llm-instructions/archive/CODE_REVIEW_PLAN.md (archived) Pass B.

Inventory Types

Inventory	What to Extract	Where to Look	Merge Destination
DB Schema	Tables, columns, relationships, enums	`database/migrations/`	sds-04-data-architecture.md
Events	Event classes, triggers, payloads	`app/Events/`	sds-domain-audit.md
Integrations	S3/SES/Pusher/Cognito touchpoints	`app/Support/`, services	sds-03-architecture-overview.md
Jobs & Queues	Job classes, triggers, failure handling	`app/Jobs/`	sds-06-cross-cutting.md
Auth	Middleware, guards, token logic	`app/Http/Middleware/`, auth controllers	sds-05-security-architecture.md
Audit Events	Event types, emitters, captured fields	`app/Events/*Event.php`, listeners	sds-domain-audit.md

Extraction Commands

# DB Schema - list all migrations
ls -la database/migrations/app/

# Events - list all event classes
find app/Events -name "*.php" -type f

# Jobs - list all job classes
find app/Jobs -name "*.php" -type f

# Broadcast events (Pusher)
grep -r "implements ShouldBroadcast" app/Events/

# Audit events
grep -r "implements AuditableEvent" app/Events/

Parallelization

All 6 inventories are independent. Run extraction agents concurrently:

Agent 1: DB Schema extraction
Agent 2: Events extraction
Agent 3: Integrations extraction
Agent 4: Jobs extraction
Agent 5: Auth extraction
Agent 6: Audit extraction

Domain Mapping (From Pass C Patterns)

Reference: llm-instructions/archive/PASS_C_DOMAIN_MAPPING.md (archived) contains the complete domain-to-code mapping.

Key Domains and Code Boundaries

Domain	SRS File	Key Code Boundaries
Auth/User Mgmt	user-management.md	`Auth/Controller`, `UserManagement/`, `CognitoAuthenticator`
File Import	fileimport.md, upload-runs.md	`RunController`, `RunImportService`, `ProcessRunFileJob`
Rules & Analytics	analytics.md, rules/*.md	`RulesEngine`, `app/Rules/*`, `AnalyticsService`
Audit	audit-log.md	`AuditService`, listeners, `*Event.php`
Kit Config	kitcfg.md	`Kit*Controller`, `MixRepository`, `TargetRepository`
Run Management	runfile-list.md, runfile-report.md	`RunController`, `Run.php`, `Well.php`
Comments	comments.md	`CommentsController`, `Comment.php`
Reporting	reports.md	`Report*Controller`, export services

Using Domain Mapping for Change Detection

# For a changed controller, find the SRS domain
# Example: RunController changed
grep -l "RunController" llm-instructions/archive/PASS_C_DOMAIN_MAPPING.md
# Shows it maps to: fileimport.md, upload-runs.md, runfile-list.md

Tips

Start with commit messages - Well-written commits tell you what changed and why
Focus on entry points first - Controllers and page components reveal feature changes
Check migrations carefully - Schema changes often indicate significant feature changes
Note breaking changes - API changes, removed features need extra documentation
Track cross-cutting changes - Security, audit, config affect multiple docs
Use PASS_C_DOMAIN_MAPPING.md - Don't reinvent domain-to-code mappings
Extract inventories for major changes - Comprehensive view before doc updates
Parallelize inventory extraction - All 6 types are independent

Sources of Change​

Step 1: Review PRD/Specification Changes​

Step 1b: Convert Confluence Exports (If Applicable)​

Step 2: Analyze Code Changes​

High-Level Overview​

Backend Changes (PHP/Laravel)​

Frontend Changes (Vue/TypeScript)​

Configuration Changes​

Step 3: Review Test Changes​

Step 4: Categorize Changes​

Step 5: Create Change Manifest​

Template​

Automation Scripts​

Generate Change Summary​

Find REQ References in Changed Files​

Inventory Extraction (From Pass B Patterns)​

Inventory Types​

Extraction Commands​

Parallelization​

Domain Mapping (From Pass C Patterns)​

Key Domains and Code Boundaries​

Using Domain Mapping for Change Detection​

Tips​