feat: use devtrail analyze as primary doc trigger with >20 lines fallback (#31)

montfort · claude · web-flow · commit ada5e8242e25 · 2026-04-02T12:32:32.000-06:00
Replace the static "&gt;20 lines of business logic" heuristic with a
two-tier approach: agents now run `devtrail analyze --output json` on
changed files and create AILOGs when `summary.above_threshold &gt; 0`.
The &gt;20 lines rule is preserved as an explicit fallback when the CLI
is unavailable.

Updated 18 files across governance (AGENT-RULES, DEVTRAIL.md,
AI-GOVERNANCE-POLICY, QUICK-REFERENCE), agent directives (Claude,
Gemini, Copilot, Cursor), skills/workflows, and CLI-REFERENCE docs
in both EN and ES.

Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/dist/.agent/workflows/devtrail-new.md b/dist/.agent/workflows/devtrail-new.md
@@ -32,6 +32,10 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat
 
 # Count lines changed
 git diff --numstat HEAD~1 2>/dev/null || git diff --numstat
+
+# Check code complexity (primary method for AILOG trigger)
+devtrail analyze --output json 2>/dev/null
+# If CLI unavailable, fall back to line count heuristic in step 3
 ```
 
 ### 3. Classify and Suggest Type
@@ -40,7 +44,7 @@ Based on the analysis, suggest a document type:
 
 | Pattern | Suggested Type |
 |---------|---------------|
-| New code in `src/`, `lib/`, `app/` (>20 lines) | AILOG |
+| Complex code (`devtrail analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG |
 | Multiple implementation alternatives discussed | AIDEC |
 | Structural/architectural changes, new modules | ADR |
 | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) |
diff --git a/dist/.claude/skills/devtrail-new/SKILL.md b/dist/.claude/skills/devtrail-new/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: devtrail-new
 description: Create DevTrail documentation. Analyzes context to suggest document type or accepts explicit type parameter. Always confirms before creating.
-allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *)
+allowed-tools: Read, Write, Glob, Bash(git diff *, git log *, git status *, date *, wc *, devtrail analyze *)
 ---
 
 # DevTrail New Skill
@@ -34,6 +34,10 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat
 
 # Count lines changed
 git diff --numstat HEAD~1 2>/dev/null || git diff --numstat
+
+# Check code complexity (primary method for AILOG trigger)
+devtrail analyze --output json 2>/dev/null
+# If CLI unavailable, fall back to line count heuristic in step 3
 ```
 
 ### 3. Classify and Suggest Type
@@ -42,7 +46,7 @@ Based on the analysis, suggest a document type:
 
 | Pattern | Suggested Type |
 |---------|---------------|
-| New code in `src/`, `lib/`, `app/` (>20 lines) | AILOG |
+| Complex code (`devtrail analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG |
 | Multiple implementation alternatives discussed | AIDEC |
 | Structural/architectural changes, new modules | ADR |
 | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) |
diff --git a/dist/.devtrail/00-governance/AGENT-RULES.md b/dist/.devtrail/00-governance/AGENT-RULES.md
@@ -28,7 +28,7 @@ confidence: high | medium | low
 
 | Situation | Type | Notes |
 |-----------|------|-------|
-| >20 lines of business logic | AILOG | Use qualitative judgment for borderline cases |
+| Code complexity above threshold | AILOG | Run `devtrail analyze <changed-files> --output json`. If `summary.above_threshold > 0`, create AILOG (default threshold: 8). **Fallback**: if CLI unavailable, apply >20 lines of business logic heuristic |
 | Decision between 2+ technical alternatives | AIDEC | Document alternatives |
 | Changes in auth/authorization/PII | AILOG + ETH | `risk_level: high`, ETH requires approval |
 | Changes in public API or DB schema | AILOG | `risk_level: medium+`, consider ADR |
@@ -37,7 +37,6 @@ confidence: high | medium | low
 | Addition/removal/upgrade of security-critical dependencies | AILOG | Human review required |
 | Changes affecting AI system lifecycle (deployment, retirement) | AILOG + ADR | Human review required |
 | Changes to OTel instrumentation (spans, attributes, pipeline) | AILOG | Tag `observabilidad`, see §9 |
-| Function with cognitive complexity > threshold | AILOG | Run `devtrail analyze` to identify; default threshold: 8 |
 
 ### PROHIBITED - Do not document
 
diff --git a/dist/.devtrail/00-governance/AI-GOVERNANCE-POLICY.md b/dist/.devtrail/00-governance/AI-GOVERNANCE-POLICY.md
@@ -193,7 +193,7 @@ Per AGENT-RULES.md, documentation is required when:
 - Changes affect auth/authorization/PII → AILOG + ETH draft
 - Changes in public API or DB schema → AILOG
 - Changes in ML models or AI prompts → AILOG + human review
-- Business logic changes > 20 lines → AILOG
+- Code above cognitive complexity threshold (run `devtrail analyze`; fallback: >20 lines) → AILOG
 - Decision between 2+ alternatives → AIDEC
 - Security-critical dependency changes → AILOG + human review
 
diff --git a/dist/.devtrail/00-governance/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/QUICK-REFERENCE.md
@@ -63,7 +63,7 @@ language: en  # Options: en, es (default: en)
 
 | Situation | Action |
 |-----------|--------|
-| >20 lines business logic | AILOG |
+| Complex code (`devtrail analyze`; fallback: >20 lines) | AILOG |
 | Decision between alternatives | AIDEC |
 | Auth/authorization/PII changes | AILOG + `risk_level: high` + ETH |
 | Public API or DB schema changes | AILOG + consider ADR |
diff --git a/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md b/dist/.devtrail/00-governance/i18n/es/AGENT-RULES.md
@@ -30,7 +30,7 @@ confidence: high | medium | low
 
 | Situación | Tipo | Notas |
 |-----------|------|-------|
-| >20 líneas de lógica de negocio | AILOG | Usar juicio cualitativo para casos límite |
+| Complejidad de código sobre el umbral | AILOG | Ejecutar `devtrail analyze <archivos-modificados> --output json`. Si `summary.above_threshold > 0`, crear AILOG (umbral por defecto: 8). **Alternativa**: si el CLI no está disponible, usar heurística de >20 líneas de lógica de negocio |
 | Decisión entre 2+ alternativas técnicas | AIDEC | Documentar alternativas |
 | Cambios en auth/autorización/PII | AILOG + ETH | `risk_level: high`, ETH requiere aprobación |
 | Cambios en API pública o esquema de BD | AILOG | `risk_level: medium+`, considerar ADR |
@@ -39,7 +39,6 @@ confidence: high | medium | low
 | Adición/eliminación/actualización de dependencias críticas de seguridad | AILOG | Revisión humana requerida |
 | Cambios que afectan el ciclo de vida del sistema de IA (despliegue, retirada) | AILOG + ADR | Revisión humana requerida |
 | Cambios en instrumentación OTel (spans, atributos, pipeline) | AILOG | Tag `observabilidad`, ver §9 |
-| Función con complejidad cognitiva > umbral | AILOG | Ejecutar `devtrail analyze` para identificar; umbral por defecto: 8 |
 
 ### PROHIBIDO - No documentar
 
diff --git a/dist/.devtrail/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md b/dist/.devtrail/00-governance/i18n/es/AI-GOVERNANCE-POLICY.md
@@ -193,7 +193,7 @@ Según AGENT-RULES.md, la documentación es requerida cuando:
 - Cambios que afectan auth/autorización/PII → AILOG + borrador ETH
 - Cambios en API pública o esquema de BD → AILOG
 - Cambios en modelos ML o prompts de IA → AILOG + revisión humana
-- Cambios en lógica de negocio > 20 líneas → AILOG
+- Código sobre umbral de complejidad cognitiva (ejecutar `devtrail analyze`; alternativa: >20 líneas) → AILOG
 - Decisión entre 2+ alternativas → AIDEC
 - Cambios en dependencias críticas de seguridad → AILOG + revisión humana
 
diff --git a/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.devtrail/00-governance/i18n/es/QUICK-REFERENCE.md
@@ -63,7 +63,7 @@ language: en  # Opciones: en, es (por defecto: en)
 
 | Situación | Acción |
 |-----------|--------|
-| >20 líneas lógica de negocio | AILOG |
+| Código complejo (`devtrail analyze`; alternativa: >20 líneas) | AILOG |
 | Decisión entre alternativas | AIDEC |
 | Cambios en auth/autorización/PII | AILOG + `risk_level: high` + ETH |
 | Cambios en API pública o esquema de BD | AILOG + considerar ADR |
diff --git a/dist/.devtrail/QUICK-REFERENCE.md b/dist/.devtrail/QUICK-REFERENCE.md
@@ -160,7 +160,7 @@ Mark `review_required: true` when:
 
 | I just... | Create |
 |-----------|--------|
-| Implemented >20 lines | AILOG |
+| Implemented complex logic | AILOG |
 | Chose between options | AIDEC |
 | Fixed security issue | AILOG + `risk_level: high` |
 | Found tech debt | TDE |
diff --git a/dist/.gemini/skills/devtrail-new/SKILL.md b/dist/.gemini/skills/devtrail-new/SKILL.md
@@ -33,6 +33,10 @@ git diff --stat HEAD~1 2>/dev/null || git diff --stat
 
 # Count lines changed
 git diff --numstat HEAD~1 2>/dev/null || git diff --numstat
+
+# Check code complexity (primary method for AILOG trigger)
+devtrail analyze --output json 2>/dev/null
+# If CLI unavailable, fall back to line count heuristic in step 3
 ```
 
 ### 3. Classify and Suggest Type
@@ -41,7 +45,7 @@ Based on the analysis, suggest a document type:
 
 | Pattern | Suggested Type |
 |---------|---------------|
-| New code in `src/`, `lib/`, `app/` (>20 lines) | AILOG |
+| Complex code (`devtrail analyze` `above_threshold > 0`; fallback: >20 lines) | AILOG |
 | Multiple implementation alternatives discussed | AIDEC |
 | Structural/architectural changes, new modules | ADR |
 | Files with `auth`, `user`, `privacy`, `gdpr` | ETH (draft) |
diff --git a/dist/DEVTRAIL.md b/dist/DEVTRAIL.md
@@ -54,7 +54,7 @@ DevTrail: Created AILOG-2025-01-27-001-implement-auth.md
 
 **If documentation was not needed:**
 ```
-DevTrail: No documentation required (minor change / <20 lines)
+DevTrail: No documentation required (minor change / below complexity threshold)
 ```
 
 **If you should have documented but didn't:**
@@ -123,7 +123,7 @@ gh pr create --title "fix: description" --body "..."
 
 | Situation | Action |
 |-----------|--------|
-| >20 lines of business logic | Create AILOG |
+| Code complexity above threshold | Create AILOG — run `devtrail analyze <files> --output json`; fallback: >20 lines |
 | Decision between technical alternatives | Create AIDEC |
 | Changes in auth/authorization/PII | Create AILOG (`risk_level: high`) + ETH draft |
 | Changes in public API or DB schema | Create AILOG + consider ADR |
diff --git a/dist/dist-templates/directives/CLAUDE.md b/dist/dist-templates/directives/CLAUDE.md
@@ -24,7 +24,7 @@
 
 Before committing, check:
 - [ ] Changed auth/PII/security code? → Create AILOG (`risk_level: high`) + ETH draft
-- [ ] Changed >20 lines of business logic? → Create AILOG
+- [ ] Complex code change? → Run `devtrail analyze <changed-files> --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines)
 - [ ] Chose between 2+ alternatives? → Create AIDEC
 - [ ] Changed public API or DB schema? → Create AILOG + consider ADR
 - [ ] Changed ML model/prompts? → Create AILOG + human review
diff --git a/dist/dist-templates/directives/GEMINI.md b/dist/dist-templates/directives/GEMINI.md
@@ -24,7 +24,7 @@
 
 Before committing, check:
 - [ ] Changed auth/PII/security code? → Create AILOG (`risk_level: high`) + ETH draft
-- [ ] Changed >20 lines of business logic? → Create AILOG
+- [ ] Complex code change? → Run `devtrail analyze <changed-files> --output json`; if `above_threshold > 0` create AILOG (fallback if CLI unavailable: >20 lines)
 - [ ] Chose between 2+ alternatives? → Create AIDEC
 - [ ] Changed public API or DB schema? → Create AILOG + consider ADR
 - [ ] Changed ML model/prompts? → Create AILOG + human review
diff --git a/dist/dist-templates/directives/copilot-instructions.md b/dist/dist-templates/directives/copilot-instructions.md
@@ -12,7 +12,7 @@
 When assisting with code changes in this project, follow these documentation rules:
 
 **Document when:**
-- Changing >20 lines of business logic → suggest creating AILOG
+- Complex code change → suggest running `devtrail analyze`; if `above_threshold > 0`, suggest AILOG (fallback: >20 lines)
 - Choosing between alternatives → suggest creating AIDEC
 - Changing auth/PII/security → suggest AILOG (risk_level: high) + ETH draft
 - Changing public API or DB schema → suggest AILOG + consider ADR
diff --git a/dist/dist-templates/directives/cursor-rules-devtrail.md b/dist/dist-templates/directives/cursor-rules-devtrail.md
@@ -7,7 +7,7 @@
 
 Identity: Use `cursor-v{version}` in the `agent:` field.
 
-Document when: >20 lines business logic (AILOG), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review).
+Document when: complex code — run `devtrail analyze <files> --output json`, AILOG if `above_threshold > 0` (fallback: >20 lines), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review).
 
 Review required: ETH, ADR, SEC, MCARD, DPIA → always. risk_level high/critical → always.
 
diff --git a/dist/dist-templates/directives/cursorrules b/dist/dist-templates/directives/cursorrules
@@ -7,7 +7,7 @@
 
 Identity: Use `cursor-v{version}` in the `agent:` field.
 
-Document when: >20 lines business logic (AILOG), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review).
+Document when: complex code — run `devtrail analyze <files> --output json`, AILOG if `above_threshold > 0` (fallback: >20 lines), alternatives (AIDEC), auth/PII (AILOG+ETH), API/DB changes (AILOG+ADR), ML/prompts (AILOG+review).
 
 Review required: ETH, ADR, SEC, MCARD, DPIA → always. risk_level high/critical → always.
 
diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md
@@ -519,6 +519,8 @@ $ devtrail analyze /path/to/project
 
 > **Note:** This command works without `devtrail init`. It operates on source files, not DevTrail documents. The `analyze` feature can be disabled at compile time with `--no-default-features`.
 
+> **Documentation trigger:** AI agents use `devtrail analyze --output json` as the primary method to determine when to create AILOG documents. If `summary.above_threshold > 0` in the JSON output, the agent should create an AILOG. When the CLI is not available, agents fall back to the >20 lines of business logic heuristic.
+
 ---
 
 ### `devtrail audit [path] [--from <date>] [--to <date>] [--system <name>] [--output <format>]`
diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md
@@ -417,6 +417,8 @@ $ devtrail analyze /ruta/al/proyecto
 
 > **Nota:** Este comando funciona sin `devtrail init`. Opera sobre archivos fuente, no documentos DevTrail. La feature `analyze` se puede desactivar en compilación con `--no-default-features`.
 
+> **Trigger de documentación:** Los agentes de IA usan `devtrail analyze --output json` como método primario para determinar cuándo crear documentos AILOG. Si `summary.above_threshold > 0` en la salida JSON, el agente debe crear un AILOG. Cuando el CLI no está disponible, los agentes usan la heurística de >20 líneas de lógica de negocio como alternativa.
+
 ---
 
 ### `devtrail audit [path] [--from <fecha>] [--to <fecha>] [--system <nombre>] [--output <formato>]`
