Skip to main content
conflict-resolution Step-by-step remediation procedures for the consistency rules used by /architect:validate-consistency --fix
Ir a la instalación Skills Marketplace Descubre y explora habilidades de IA creadas por la comunidad.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Mostrar detalles del prompt Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.
npx skills add https://github.com/navraj007in/architecture-cowork-plugin --skill conflict-resolutionEl comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.
¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.
Descargar Zip Descargando... Ocupaciones relacionadas
SOC
Basado en la clasificación ocupacional SOC
name conflict-resolution description Step-by-step remediation procedures for the consistency rules used by /architect:validate-consistency --fix
Conflict Resolution Guide
Step-by-step remediation procedures for each of the 23 consistency rules. Used by /architect:validate-consistency --fix to auto-fix safe conflicts, and by users to manually resolve complex conflicts.
Quick Reference
For each conflict type, this guide provides:
Root cause — why the conflict happenedImpact — what goes wrong if not fixedAuto-fix approach — if /architect:validate-consistency --fix can handle itManual fix steps — for when user judgment is needed
State Conflicts (RULE-S-001 through RULE-S-006)
RULE-S-001: Invalid design color format
Conflict: Design color field is not a valid hex code.
Root cause: Typo when editing _state.json, or pasted from color picker in wrong format.
Impact: Design token generation fails or produces broken CSS variables.
Auto-Fix
✅ If color is "f97316" (missing #), add prefix → "#f97316"
✅ If color is "rgb(249, 115, 22)", convert to nearest hex
✅ If color is "#F97316" (wrong case), normalize to lowercase
✅ If color has alpha like "#f97316ff", strip alpha → "#f97316"
Manual Fix
If auto-fix rejected the color:
jq '.design | to_entries[] | select(.value | test("^#?[0-9a-fA-F]{6}$") | not)' _state.json
'.design.primary = "#<new-hex>"'
mv
'.design.primary'
RULE-S-002: Duplicate or invalid component ports Conflict: Two components claim the same port, or port is not numeric.
Root cause: Copy-pasted component without changing port, or manually edited _state.json with invalid value.
Impact: Local dev server fails with "EADDRINUSE: port already in use".
Auto-Fix
✅ If port is string "3000", convert to number 3000
❌ Cannot auto-fix duplicate ports (requires user choice)
❌ Cannot auto-fix out-of-range ports (1024-65535) without knowing what port to use
Manual Fix
jq '.components[] | {name, port}' _state.json | sort
jq '.components[] | select(.name=="worker-service").port = 3001' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.components[].port' _state.json | sort | uniq -d
jq '.components[] | select(.port < 1024 or .port > 65535) | {name, port}' _state.json
jq '.components[] | select(.name=="api-server").port = 3000' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.components[].port' _state.json | awk '$1 < 1024 || $1 > 65535 { print "INVALID:", $0 }'
RULE-S-003: Entity in state but not in schema Conflict: _state.json.entities[] references entity not defined in data model schema.
Root cause: Entity added to state manually, but schema wasn't regenerated.
Impact: Future scaffold code generation will miss this entity's ORM definition.
Auto-Fix
❌ Cannot auto-fix (requires investigating: is entity real or mistake?)
Manual Fix Option A: Add entity to schema
jq '.entities[] | select(.name=="Order")' _state.json
/architect:generate-data-model --regenerate
grep -A 20 "model Order" architecture-output/data-model/schema.prisma
/architect:validate-consistency
Option B: Remove entity from state (if it's a mistake)
jq '.entities[] | select(.name=="Order")' _state.json
jq 'del(.entities[] | select(.name=="Order"))' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.entities[] | select(.name=="Order")' _state.json
/architect:validate-consistency
RULE-S-004: Invalid tech stack version format Conflict: Version string doesn't parse as valid semver.
Root cause: Typo like "Node.js v18" or "latest" instead of numeric version.
Impact: Deployment scripts can't pin versions correctly.
Auto-Fix
✅ If version is "v18", remove 'v' → "18"
✅ If version is "18.2", treat as 18.2.0
✅ If version has extra parts like "18.2.1.5", use first 3 parts → "18.2.1"
❌ Cannot auto-fix non-numeric like "latest"
Manual Fix
jq '.tech_stack | to_entries[]' _state.json | grep -v '[0-9]'
jq '.tech_stack.backend[0] = "Node.js 18.2.1"' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.tech_stack.backend[0]' _state.json
/architect:validate-consistency
RULE-S-005: Duplicate persona or decision IDs Conflict: Two personas/decisions share the same ID.
Root cause: Copy-pasted entry without updating ID.
Impact: Tracking and decision audit is ambiguous; unclear which entry is meant.
Auto-Fix
❌ Cannot auto-fix (would require renumbering, which breaks references)
Manual Fix
jq '.personas[].id' _state.json | sort | uniq -d
jq '.personas[] |= if .id == "P-003" and .name == "Secondary Persona" then .id = "P-004" else . end' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.personas[].id' _state.json | sort | uniq -d
/architect:validate-consistency
RULE-S-006: Broken references in state Conflict: One field references another field that doesn't exist.
Root cause: Deleted a field but didn't clean up references, or typo in field name.
Impact: Downstream commands that expect reference to resolve will fail.
Auto-Fix
✅ If reference is null/undefined, remove it
✅ If reference is typo (close match), suggest correction
❌ If reference is legitimately broken, requires investigation
Manual Fix
jq '.personas[] | select(.skills[]? == "unknown_skill")' _state.json
jq '.skills += ["unknown_skill"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.personas[] |= .skills |= map(select(. != "unknown_skill"))' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.personas[].skills[]' _state.json
/architect:validate-consistency
Output Conflicts (RULE-O-001 through RULE-O-008)
RULE-O-001: Design tokens don't match state colors Conflict: _state.json.design.primary is #f97316, but design-tokens.json.primary is #0ea5e9.
Root cause: Blueprint updated state colors, but design-system command didn't regenerate tokens.
Impact: New components use one color, old components use another → inconsistent UI.
Auto-Fix
✅ If tokens file is older than state file, use state colors
❌ If both are recent, ask user which source is correct
Manual Fix Decide which color is right:
echo "State color:" && jq '.design.primary' _state.json
echo "Token color:" && jq '.primary' design-system/design-tokens.json
git log --oneline _state.json | head -3
git log --oneline design-system/design-tokens.json | head -3
/architect:design-system --regenerate
git show <blueprint-commit>:_state.json | jq '.design.primary' > old_color.txt
echo "After fix:" && jq '.design.primary' _state.json && jq '.primary' design-system/design-tokens.json
RULE-O-002: Scaffold missing components from state Conflict: _state.json defines component "auth-service", but no src/services/auth-service/ folder exists.
Root cause: Component added to state, but scaffold not regenerated.
Impact: Incomplete project structure; dev expects service to exist.
Auto-Fix
❌ Cannot auto-fix (requires running scaffold or scaffold-component)
Manual Fix
jq '.components[].name' _state.json | while read c; do
c_kebab=$(echo "$c " | sed 's/[A-Z]/-\L&/g' )
if [ ! -d "src/services/$c_kebab " ] && [ ! -d "src/components/$c_kebab " ]; then
echo "Missing: $c "
fi
done
/architect:scaffold
/architect:scaffold-component --name auth-service
ls -la src/services/ | grep auth-service
ls -la src/components/ | grep auth-service
/architect:validate-consistency
RULE-O-003: Cost estimate is stale Conflict: Cost estimate was generated 30 days ago with 8 components; state now has 12 components.
Root cause: Cost estimate wasn't regenerated after architecture changed.
Impact: Budget projections are 25% undercounted.
Auto-Fix
✅ Can detect staleness, but regeneration requires running command
Manual Fix
ls -la architecture-output/cost-estimate.md
/architect:cost-estimate --regenerate
echo "Old estimate:" && grep -A 5 "monthly" cost-estimate.md.backup
echo "New estimate:" && grep -A 5 "monthly" architecture-output/cost-estimate.md
/architect:validate-consistency
RULE-O-004: Invalid test coverage percentage Conflict: Test coverage is reported as 150% (impossible).
Root cause: Bug in test command, or manual edit of coverage field.
Impact: Dashboards break; coverage metrics are nonsensical.
Auto-Fix
✅ Clamp to 0-100 range
✅ If >100, use 100; if <0, use 0
Manual Fix
jq '.test_suite.coverage' architecture-output/_state.json
jq '.test_suite.coverage = 100' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.test_suite.coverage = 0' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.test_suite.coverage' _state.json
/architect:generate-tests --regenerate
RULE-O-005: Compliance rule references nonexistent entity Conflict: Compliance rule says "encrypt User entity data", but no User entity in state.
Root cause: Compliance plan generated for wrong project, or entity was deleted.
Impact: Compliance checklist includes impossible tasks.
Auto-Fix
❌ Cannot auto-fix (requires investigation)
Manual Fix
jq '.entities[].name' _state.json
jq '.compliance.controls[] | select(.applies_to_entity)' architecture-output/_state.json
jq '.entities += [{name: "User", fields: ["id", "email"]}]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
vi architecture-output/compliance-report.md
jq '.compliance.controls[]' architecture-output/_state.json
/architect:validate-consistency
RULE-O-006: Monitoring metrics reference unavailable services Conflict: Monitoring plan includes Kafka metrics, but tech stack is RabbitMQ.
Root cause: Monitoring plan copied from different project, or tech stack changed without updating monitoring.
Impact: Monitoring won't work; can't monitor services that don't exist.
Auto-Fix
❌ Cannot auto-fix (requires choosing monitoring provider)
Manual Fix
jq '.tech_stack.backend' _state.json | grep -i kafka
jq '.monitoring.metrics[].service' architecture-output/_state.json | sort | uniq
jq '.tech_stack.backend += ["Kafka"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
sed -i 's/kafka/rabbitmq/g' architecture-output/monitoring.md
echo "Tech stack:" && jq '.tech_stack.backend[]' _state.json
echo "Monitoring:" && jq '.monitoring.metrics[].service' architecture-output/_state.json
/architect:validate-consistency
RULE-O-007: Load test references nonexistent endpoints Conflict: Load test scenario requests GET /api/orders, but API contract doesn't define this endpoint.
Root cause: Load test copied from template, endpoints changed, or API wasn't scaffolded yet.
Impact: Load tests won't run; endpoints don't exist.
Auto-Fix
❌ Cannot auto-fix (requires either adding endpoint or removing test scenario)
Manual Fix
jq '.paths | keys[]' contracts/api-server.openapi.yaml | sort
grep -n "/api/orders" architecture-output/load-test.md
grep -o '/api/[a-z/]*' architecture-output/load-test.md | sort | uniq
jq '.paths | keys[]' contracts/api-server.openapi.yaml
/architect:validate-consistency
RULE-O-008: Documentation references deleted components Conflict: API docs mention "auth-service" component, but component was removed.
Root cause: Component removed from project, docs not updated.
Impact: Docs are outdated and confusing.
Auto-Fix
❌ Cannot auto-fix (requires manual doc updates)
Manual Fix
jq '.components[].name' _state.json
grep -r "auth-service" architecture-output/ | grep -v "\.json"
jq '.components += [{name: "auth-service"}]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
sed -i '/auth-service/d' architecture-output/api-docs.md
grep -r "auth-service" architecture-output/
/architect:validate-consistency
Cross-Command Conflicts (RULE-X-001 through RULE-X-009)
RULE-X-001: Component in both created and removed lists Conflict: Component "worker-service" was scaffolded, but also appears in deprecated list.
Root cause: Component removed from project, but state wasn't fully updated.
Impact: Architectural ambiguity; unclear if service should exist.
Auto-Fix
❌ Cannot auto-fix (requires deciding: keep or remove?)
Manual Fix
jq '.components[] | select(.name=="worker-service")' _state.json
jq '.deprecated_components[]' _state.json | grep worker-service
jq '.deprecated_components -= ["worker-service"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.components |= map(select(.name != "worker-service"))' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.components[].name' _state.json | grep -c worker-service
RULE-X-002: Design personality inconsistency Conflict: State personality is "bold-commercial", but scaffold components use "serene-health" styling.
Root cause: Design personality changed in state, but scaffold wasn't regenerated.
Impact: Visual inconsistency; brand confusion.
Auto-Fix
❌ Cannot auto-fix (requires regenerating scaffold with new personality)
Manual Fix
jq '.design.personality' _state.json
/architect:design-system --regenerate
/architect:scaffold --regenerate
grep -r "personality\|className" src/components/ | head -5
/architect:validate-consistency
RULE-X-003: Entity count decreased Conflict: State had 8 entities last week, now has 5 (3 were deleted).
Root cause: Refactoring or mistake; entities were removed without audit trail.
Impact: Unclear what happened to old entities; backward compatibility issues.
Auto-Fix
❌ Cannot auto-fix (requires investigating why entities disappeared)
Manual Fix
git log --oneline -- _state.json | head -5
git diff HEAD~1 _state.json | grep -A 2 "entities"
git show HEAD~1:_state.json | jq '.entities[].name' > old_entities.txt
jq '.entities[].name' _state.json > new_entities.txt
diff old_entities.txt new_entities.txt
git show HEAD~1:_state.json | jq '.entities' > entities_backup.json
jq '.entities = input' _state.json entities_backup.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.decisions += [{id: "D-NNN", title: "Remove X entity for simplification", made_by_command: "manual", timestamp: "2026-04-24T..."}]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.entities[].name' _state.json
/architect:validate-consistency
RULE-X-004: Blueprint and scaffold architecture mismatch Conflict: Blueprint describes 3 services (api-server, web-app, worker), but scaffold only has 2 (api-server, web-app).
Root cause: Blueprint updated, or scaffold wasn't regenerated.
Impact: Implementation doesn't match architecture; developer confusion.
Auto-Fix
❌ Cannot auto-fix (requires deciding which is correct)
Manual Fix
echo "Blueprint services:" && jq '.blueprint.services[].name' _state.json
echo "Scaffold components:" && jq '.components[].name' _state.json
/architect:scaffold-component --name worker-service
/architect:validate-consistency
RULE-X-005: Tech stack language doesn't match codebase Conflict: Tech stack lists "Python", but codebase has only .ts (TypeScript) files.
Root cause: Tech stack auto-detected wrong, or codebase changed after tech stack was set.
Impact: Deployment, CI/CD, and documentation use wrong tooling.
Auto-Fix
✅ Can suggest correction based on file extension analysis
Manual Fix
find src -name "*.ts" -o -name "*.tsx" | wc -l
find src -name "*.py" | wc -l
find src -name "*.go" | wc -l
jq '.tech_stack.backend = ["Node.js", "TypeScript"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.tech_stack.backend' _state.json
/architect:validate-consistency
RULE-X-006: Monitoring provider not in tech stack Conflict: Monitoring setup uses "Datadog", but tech_stack.integrations doesn't list Datadog.
Root cause: Added monitoring without updating tech stack.
Impact: Minor (monitoring will still work, but tech stack list is incomplete).
Auto-Fix
✅ Add monitoring provider to integrations list
Manual Fix
jq '.monitoring.provider' architecture-output/_state.json
jq '.tech_stack.integrations += ["Datadog"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.tech_stack.integrations[] | select(. == "Datadog")' _state.json
/architect:validate-consistency
RULE-X-007: Compliance framework unsupported by tech stack Conflict: Compliance plan requires HIPAA (health data), but tech stack uses AWS free tier (no HIPAA support).
Root cause: Compliance requirements and tech stack chosen independently.
Impact: Compliance impossible; tech stack needs upgrade or requirements need revision.
Auto-Fix
❌ Cannot auto-fix (major architectural decision)
Manual Fix Option A: Upgrade tech stack to support compliance
jq '.tech_stack.backend += ["AWS Enterprise Support"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
/architect:cost-estimate --regenerate
jq '.tech_stack.backend' _state.json
Option B: Reduce compliance scope
jq '.compliance.frameworks -= ["HIPAA"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.compliance.frameworks' _state.json
RULE-X-008: Load test target RPS unrealistic for tech stack Conflict: Load test targets 100k RPS, but tech stack is single-threaded Python (achieves ~500 RPS).
Root cause: Copy-pasted load test goals from different project, or underestimated complexity.
Impact: Load test goals are impossible; wasted time on unreachable targets.
Auto-Fix
✅ Can suggest realistic RPS based on tech stack
Manual Fix
echo "Tech stack:" && jq '.tech_stack.backend' _state.json
jq '.load_testing.target_rps = 5000' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
/architect:load-test --target-rps 5000 --regenerate
jq '.load_testing.target_rps' _state.json
jq '.load_testing.target_rps' architecture-output/_state.json
RULE-X-009: External service not in tech stack integrations Conflict: Blueprint mentions Stripe payment integration, but tech_stack.integrations doesn't list Stripe.
Root cause: Service added to blueprint, tech stack list not updated.
Impact: Cost estimation and deployment scripts miss this service.
Auto-Fix
✅ Add service to integrations list
Manual Fix
grep -i "stripe\|sendgrid\|auth0" architecture-output/blueprint.md
jq '.tech_stack.integrations += ["Stripe", "SendGrid"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json
jq '.tech_stack.integrations[]' _state.json | grep -i stripe
/architect:validate-consistency
Fixing Multiple Conflicts When /architect:validate-consistency reports multiple conflicts, follow this order:
Step 1: Fix state conflicts first (RULE-S-xxx)
These are the foundation
All other checks depend on valid state
Time: 5-30 min total
Step 2: Fix output conflicts (RULE-O-xxx)
Design, cost, test, compliance
Depends on valid state
Time: 10-45 min total
Step 3: Fix cross-command conflicts (RULE-X-xxx)
Blueprint, scaffold, tech stack alignment
Depends on valid state + outputs
Time: 15-60 min total
Step 4: Re-run validate-consistency
Confirm all conflicts resolved
Fix any cascading issues
Time: 2 min
Conflict Resolution Workflow
/architect:validate-consistency
/architect:validate-consistency --fix
/architect:validate-consistency
When to Ask for Help If you hit a conflict you can't resolve:
Read the conflict reasoning in detailed mode:
/architect:validate-consistency --detailed | grep -A 10 "CONFLICT-XXX"
Check what changed recently:
git log --oneline -10 -- architecture-output/_state.json
git diff HEAD~1 _state.json | grep -A 5 "key-that-changed"
Ask for guidance:
"I have a conflict in X — should I keep version A or B?"
"Two components claim port 3000 — which should move?"
"Entity was deleted — should I restore or update docs?"
The root cause is usually:
State changed, outputs didn't → regenerate outputOutputs changed, state didn't → update stateUser choice needed → decide and implement
Related Commands
/architect:validate-consistency — detects conflicts/architect:validate-consistency --fix — auto-fixes safe conflicts/architect:check-state — validates state schema (different from consistency)/architect:next-steps — recommends commands to fix conflicts 