ThomasMoreAI/legal-skills-open / br/litigation/skills/juriscan-brunobracaioli
juriscan-brunobracaioli
VerifiedAnálise forense de processos judiciais brasileiros. Extrai, classifica e cruza peças processuais, detecta contradições, calcula prazos CPC e gera relatórios de risco com exportação para Obsidian. Use quando mencionar: processo judicial, petição, sentença, acórdão, contradições, prazos, timeline, análise forense, Obsidian.
docs/architecture.md
View on GitHub# Juriscan — Architecture
> **v3.1.x note:** the legacy pipeline was significantly upgraded in
> v3.1.0-legacy / v3.1.1 / v3.1.2 with a per-chunk file pattern
> (`analyzed_init.py` + `merge_chunk_analysis.py`), an executive report
> generator (`generate_report.py`), strategic recommendations with
> verbatim evidence, and Lei 14.905/2024 monetary recalculation. See
> `CHANGELOG.md` and the updated legacy pipeline flow in `CLAUDE.md`.
> This document describes primarily the agents pipeline architecture,
> which remains the long-term target but has not been validated end-to-end
> against real PDFs yet.
## TL;DR
Juriscan is a Claude Code skill that analyzes Brazilian legal proceedings.
It has two pipelines during the v2→v3 transition, and the agents pipeline
is the long-term target.
- **Python owns every deterministic computation.** Dates, BRL normalization,
CNJ parsing, CPC deadline math, schema validation, Decimal money arithmetic,
Obsidian export.
- **Native Claude Code subagents own every semantic judgment.** Segmentation,
parsing, adversarial dialectic (advogado-autor × advogado-reu × auditor),
jurisprudence verification, synthesis.
- **Zero ANTHROPIC_API_KEY.** The skill uses the user's Claude Code
subscription; subagents are invoked via the `Task` tool from `SKILL.md`.
- **Every LLM output is JSON-schema-validated and logged** before any
Python script consumes it.
## Pipeline overview
```
┌─────────────────────┐
│ PDF │
└─────────┬───────────┘
│
┌──────────▼──────────┐
│ scripts/extract_pdf │ (legacy reuses extract_and_chunk.py)
└──────────┬──────────┘
│ raw_text.txt + page_map.json
│
┌──────────▼──────────┐
│ juriscan-segmenter │ [Task, model=haiku]
└──────────┬──────────┘
│ /tmp/<run_id>-segmenter.json
│ ▲ agent_io.py validate + log
│
┌──────────▼──────────┐
│ persist_chunks.py │ — writes chunks/*.txt + index.json
└──────────┬──────────┘ with integrity gate
│
┌─────────────────┴─────────────────┐
│ Task × N (parallel, one message)│
│ juriscan-parser per chunk │
└─────────────────┬─────────────────┘
│
┌──────────▼──────────┐
│ enrich_deterministic│ — utils.dates, utils.monetary, utils.cnj
└──────────┬──────────┘ raises if mismatch rate > 10%
│
┌──────────────────────────┼──────────────────────────┐
│ Task × 3 (parallel, one message) │
│ advogado-autor advogado-reu auditor-processual │
│ (sonnet) (sonnet) (sonnet) │
└──────────────────────────┬──────────────────────────┘
│
┌──────────▼──────────┐
│ juriscan-verificador │ [Task + WebFetch, whitelist]
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ juriscan-sintetizador│ (sonnet)
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ confidence_rules.py │ — preservation invariant
└──────────┬──────────┘ + verification downgrade
│
┌──────────▼──────────┐
│ finalize.py │ — Lei 14.905 split, honorarios
└──────────┬──────────┘ (Decimal arithmetic)
│
┌──────────▼──────────┐
│ obsidian_export.py │ — _AUDITORIA, _VERIFICAÇÕES,
└─────────────────────┘ _PERSPECTIVAS added in v3
```
## Hard invariants
1. **Chunks in analyzed.json have 1:1 correspondence with files on disk.**
Enforced by `scripts/integrity_gate.py` and called from both
`schema_validator.py` and `persist_chunks.py`.
2. **`likely_range.min ≤ likely_range.max`** in all risk outputs.
Enforced by `scripts/legacy/risk_scorer.py` via sorted() + assert.
3. **Legitimate appellate reforms are not contradictions.**
`scripts/legacy/contradiction_report.py` emits `REFORMA_PARCIAL` notes
in `instance_tracking` when sentença→acórdão values differ.
4. **Sintetizador cannot drop auditor findings.**
`scripts/confidence_rules.py` raises `ConfidenceRuleError` if violated.
5. **Every Task call is logged to the audit trail.** Even failures
(with `error=...` and `schema_valid=false`).
6. **Web lookup only in the whitelist.** `scripts/agent_io.py` rejects
verificador outputs whose `source_url` host is not in
`references/whitelist_fontes.json`, as a post-hoc hard gate.
7. **Monetary mismatch rate >10% aborts the pipeline** at the
`enrich_deterministic.py` step. The dialectic layer never runs on
unreliable parser output.
8. **Budget gate:** p95 latency per run ≤ 10 minutes and total Task
invocations ≤ 30 for a 15-piece process. Enforced by
`scripts/report_metrics.py --enforce` in CI.
## Schema versions
- **v2** — `references/output_schema_v2.json`. Output of the legacy
pipeline. `schema_version` field absent or `"2.0"`.
- **v3** — `references/output_schema_v3.json`. Superset with
`run_id`, `pipeline_mode`, `process_state`, `perspectives`,
`auditor_findings`, `verifications`, `verification_summary`,
`monetary_recalculations`, `dissensos`, `resumo_executivo`,
`audit_trail_uri`. `schema_version == "3.0"`.
`scripts/schema_validator.py` auto-dispatches by the `schema_version`
field. `scripts/migrate_v2_to_v3.py` performs additive-only migration
(keys in the input are never overwritten).
## Directory map
```
.claude/agents/ 7 subagent markdown files — juriscan-*
references/ schemas, taxonomies, whitelists, binding precedents
agent_schemas/ 8 JSON schemas for subagent outputs
output_schema_v2.json legacy schema (preserved)
output_schema_v3.json new schema, superset of v2
whitelist_fontes.json authoritative hosts for verificador
scripts/
agent_io.py glue CLI: new-run / validate / log / extract-field
audit.py append-only JSONL logger
persist_chunks.py writes chunks to disk from segmenter output
enrich_deterministic.py normalizes dates/money/CNJ, makes dialectic digests
confidence_rules.py preservation invariant + verification downgrade
finalize.py Lei 14.905 + honorarios post-reform (Decimal)
report_metrics.py audit trail aggregation + budget gate
migrate_v2_to_v3.py v2 → v3 migration
schema_validator.py dispatches by schema_version
integrity_gate.py 1:1 chunk-file ↔ JSON check
prazo_calculator.py CPC deadlines, state-aware
obsidian_export.py Obsidian vault with v3 views
legacy/ retired scripts still consumed by --pipeline=legacy
tests/ 435+ pytest unit/integration tests (v3.1.2)
docs/ architecture.md, subagents.md, operations.md
```
## How the two pipelines coexist
During Phases 2–5 the agents pipeline is **opt-in** via `/juriscan --pipeline=agents`.
The legacy pipeline remains the default. Flip is the subject of Phase 6
Step 6.4 — requires the agents suite to pass the golden regression three
times in a row, then `SKILL.md` changes the default and the legacy mode
becomes `--pipeline=legacy` explicit for three more releases before removal.
Schema v2 never dies silently. `migrate_v2_to_v3.py` converts any v2
artifact into v3 additively, preserving the v2 value set unchanged.
## Prompt caching
System prompts for each subagent live in the body of
`.claude/agents/juriscan-*.md` and are stable across invocations — Claude
Code's automatic prompt cache retains them. Dynamic inputs come only
via the `prompt` parameter of each `Task` call, so the stable portion
stays at the beginning of the context window and cache hits are
maximized.
The `enrich_deterministic.make_dialectic_summary()` helper produces
compact digests of the parsed pieces for the dialectic layer, so the
three parallel advogados/auditor subagents receive structured facts
instead of raw chunk text — further reducing token count and
improving cache stability across their parallel invocations.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |