The process

The full nine-phase process, as the skill defines it. The longest document in the skill and the one that answers what actually happens to a repository.

Rendered from intransic-skills/skills/intransic/reference/process.mdat v0.2.2 · 50e2c2f38f69

The full Intransic process

Read this when running a first-time build against a repository, or a full reassessment. For a routine change or release, use the prompts in prompts/ instead — they are shorter and scoped.

The process is retrospective: it runs over a codebase that already exists and describes what is actually true of it. It is not a design exercise, and it does not improve the system. It makes the system's real state legible, and it makes claims about that state falsifiable.

Phase 1 — Repository reconnaissance

Inspect the whole repository before generating anything. At minimum: root documentation, package manifests, dependencies, source directories, API routes, database schemas and migrations, domain models, authentication and authorisation, data-access patterns, validation logic, error handling, logging and observability, background jobs, queues and event processing, infrastructure-as-code, deployment configuration, CI/CD, test structure, environment configuration, secrets handling, privacy controls, security controls, external integrations, generated documentation, ADRs, feature flags, and TODO/FIXME/deprecated paths.

Where history is available, inspect enough of it to find major architectural decisions, replaced approaches, abandoned components, and decisions the documentation no longer reflects.

Output → intransic/internal/repository-assessment.md, containing:

Repository identity — purpose, primary users or consuming systems, core jobs, architecture style, runtime components, principal data stores, external dependencies, deployment model.

Current completeness — estimated per subsystem, never as a single percentage. For each: status, evidence, confidence, significant missing work, and whether it blocks production readiness.

Documentation integrity — documentation supported by implementation; implementation missing documentation; outdated documentation; contradictory documentation; ambiguous areas.

Risk map — critical / high / medium / low / informational, each with its consequence stated. Do not equate unfinished work with poor architecture.

Phase 2 — Extract the Foundation

foundation/foundation.yaml (canonical) and foundation/FOUNDATION.md (readable). The canonical, validated description of the system's identity, boundaries and invariants.

It is authoritative over what must remain true — a change conflicting with change_constraints or a domain invariant requires explicit review. It is not authoritative over what is currently true: the Foundation is a document, and implementation and executed tests outrank it as evidence of present reality. Where the two disagree, record a contradiction and resolve it; never let a stale Foundation overrule working code, and never let code quietly redefine a ratified constraint. See the authority order in SKILL.md.

Sections, populated only where evidence supports them:

foundation:
  identity:            name, purpose, system_type, lifecycle_stage,
                       primary_jobs, intended_consumers
  boundaries:          in_scope, out_of_scope, trust_boundaries,
                       ownership_boundaries, external_dependencies
  architecture:        style, components, component_responsibilities,
                       data_flows, integration_patterns, deployment_topology,
                       synchronisation_patterns, failure_boundaries
  domain:              core_entities, invariants, state_transitions,
                       terminology, prohibited_states
  interfaces:          public_apis, internal_apis, events, scheduled_jobs,
                       schemas, compatibility_expectations
  data:                classifications, stores, retention, residency,
                       encryption, deletion, backup_and_recovery,
                       data_minimisation
  identity_and_access: authentication, authorisation, roles, service_identity,
                       tenant_isolation, privilege_constraints
  security:            controls, threat_assumptions, secret_management,
                       input_validation, dependency_controls, auditability,
                       known_gaps
  privacy:             personal_data, sensitive_data, consent,
                       de_identification, access_controls, user_rights,
                       known_gaps
  reliability:         availability_assumptions, retry_behaviour, idempotency,
                       timeouts, rate_limits, degradation_behaviour,
                       recovery_expectations
  observability:       logs, metrics, traces, audit_events, alerting,
                       correlation, redaction
  engineering:         languages, frameworks, conventions, test_strategy,
                       branching_and_release, dependency_policy,
                       migration_policy, configuration_policy
  change_constraints:  must_remain_true, changes_requiring_review,
                       prohibited_changes, backward_compatibility,
                       security_review_triggers, privacy_review_triggers
  maturity:            verified, partial, planned, unknown, contradicted
  evidence:            sources, conflicts, unresolved_questions

Every significant element carries status, confidence, evidence, last_validated, owner where inferable, and notes. Extend the schema where the repository justifies it; do not overfit to it.

change_constraints.must_remain_true is the highest-value section in the file. It is what a future contributor — human or agent — will breach without knowing.

Go to field level for data.classifications

A classification that stops at "Personal identifiers: name, email, external identity subject" describes a shape, not a checkable claim — a new field can be added to the system tomorrow and nothing here will know. Trace each class to its actual fields:

data:
  classifications:
    - class: Personal identifiers
      sensitivity: high
      examples: [name, email, external identity subject]
      fields:
        - path: Models/User.cs
          symbol: Email
        - path: Models/User.cs
          symbol: ExternalIdentitySubject

This is what lets the pii_coverage conformance-rule kind (see intransic/validation/README.md) scan real source for PII-shaped names and flag one absent from this list — a check on the Foundation from outside it, run regularly rather than only at the next full reassessment.

Register every processor, not only what reads as an "integration"

privacy.processors — cloud hosting, payment, the LLM provider, identity/auth, analytics, anything receiving personal or sensitive data:

privacy:
  processors:
    - name: …
      category: cloud_infrastructure | payment | llm_ai | identity_auth | analytics | communications | storage | other
      data_shared: [...]        # in the same vocabulary as data.classifications
      basis: …                  # contract, consent, legitimate interest, legal obligation — state it
      jurisdiction: …
      evidence: [INT-001]

F-11 requires every entry complete and its evidence resolved. This is bookkeeping, not a lawful-basis determination — it records that a basis was stated and can be checked, not that the stated basis is correct in law.

Phase 3 — Build the evidence ledger

intransic/internal/evidence-ledger.yaml. Source of truth behind every claim, public and internal.

- id: AUTH-001
  category: authentication
  claim: Authentication is delegated to an external identity provider.
  status: verified
  confidence: high
  evidence:
    - type: implementation
      path: src/…
      symbol: …
      explanation: …
    - type: configuration
      path: …
      key: …
      explanation: …
    - type: test          # strength: behavioural — what lets this be `verified`
      path: …
      test: …
      explanation: …
  contradictions: []
  public_safe: true
  public_wording: Authentication is handled through a dedicated identity provider.
  internal_notes: …
  last_validated: YYYY-MM-DD

ID prefixes, stable across revalidations: ARCH AUTH SEC PRIV DATA API REL OBS TEST OPS GOV INT.

Status follows evidence strength, not conviction

Each item establishes something different, and verified is out of reach without behavioural evidence or better — an executed test, a direct observation, deployed configuration or an external audit. The strength ladder and its per-type defaults are in SKILL.md; E-11 and E-12 enforce them.

Drop an item's strength explicitly when the citation is weaker than its type implies:

    - type: implementation
      path: src/Ports/IEvidenceStore.cs
      symbol: IEvidenceStore
      strength: existence      # interface only; no active implementation binds it
      explanation: …

The practical effect is that the claim in What the first run taught, below, could not have been marked verified: the rate-limit attributes were present in source — implementation strength — and nothing executed asserted them. The status available was implemented_unverified, and the Trust Wall would have said so.

public_wording lives here, beside its evidence, because trust/claims.json is generated from the ledger. That is what stops public wording drifting away from what supports it.

Phase 4 — Produce the Trust Wall

trust/
├── README.md              ├── privacy.md
├── trust-wall.md          ├── reliability.md
├── claims.json            ├── data-handling.md
├── architecture-summary.md├── development-practices.md
├── security.md            ├── limitations.md
                           └── verification-method.md

Factual, plain-language, useful to technical and non-technical readers, restrained rather than promotional, backed by evidence IDs, explicit about limitations, and clear about what has not been independently certified.

Do not write "enterprise-grade", "bank-grade", "fully secure", "completely private", "compliant with all applicable laws", "production ready". The validator will reject them, but the reason matters more than the rule: an unverifiable superlative makes every verifiable claim beside it less credible.

Write instead: "The repository currently implements…", "The system is designed to…", "Evidence reviewed on [date] shows…", "This control is implemented but has not been independently audited.", "This capability is partial.", "This remains a planned control."

trust-wall.md covers, in order: what the system does · what was inspected · architecture overview · data handled · identity and access · security controls · privacy controls · reliability and recovery · observability and auditability · development and testing practices · known limitations · how claims are verified · last validation date · Foundation version · evidence coverage summary.

Each claim carries a verification marker:

Status: Verified
Evidence: SEC-004, AUTH-002
Last checked: 2026-07-25

Public claims reference evidence IDs; the paths stay in the internal ledger.

Phase 5 — Internal assets

intransic/
├── README.md
├── config/     intransic.config.yaml · claim-policy.yaml · publication-policy.yaml
├── internal/   repository-assessment.md · evidence-ledger.yaml ·
│               contradiction-register.md · risk-register.md · maturity-map.md ·
│               documentation-drift.md · unresolved-questions.md ·
│               generation-report.md
├── schemas/    foundation.schema.json · evidence.schema.json · trust-claim.schema.json
├── validation/ README.md · validation-rules.yaml · validate_*.py
├── prompts/    repository-review.md · change-review.md · trust-wall-refresh.md ·
│               release-validation.md
└── reports/    initial-validation-report.md

intransic/internal/ is internal-only: repository paths, unmitigated weaknesses, active defect detail. trust/ is its public counterpart.

The validators ship in Python. If the repository has no Python and adding it is unwelcome, port them — the rules file is the contract, and it is language-neutral. Do not introduce a new language without a reason.

Phase 6 — Validation rules

See validation/README.md. Foundation integrity, Trust Wall integrity, and repository conformance. State for every check what it can and — more importantly — cannot establish. Static validation proves neither security nor correctness, and a check that implies otherwise is worse than no check.

Phase 7 — Agent operating guide

AGENTS.md at the repository root. If AGENTS.md, CLAUDE.md, CONTRIBUTING.md or an equivalent already exists, preserve its useful content and propose an integration — never blindly replace it.

It should tell an agent: what to read before editing · the core purpose · architectural boundaries · domain invariants · security and privacy constraints · which files are authoritative · which are generated · prohibited actions · required tests · required Foundation updates · when human review is mandatory · how to cite evidence for a proposed change · how to identify contradictions · how to run validation.

Include a mandatory pre-change and post-change checklist.

Phase 8 — Reusable prompts

Already written, in prompts/. Copy them across and fill in the repository-specific sections marked in repository-review.md.

Phase 9 — Score the repository

intransic/reports/initial-validation-report.md. Score separately — architecture clarity · documentation alignment · domain-model clarity · security evidence · privacy evidence · test evidence · reliability evidence · observability evidence · deployment evidence · AI-agent readiness · Trust Wall publishability · overall Foundation confidence.

0 no evidence · 1 fragmentary · 2 partial · 3 credible · 4 strong · 5 comprehensive and continuously validated.

Each score carries a rationale, evidence IDs, the principal gap, and the recommended next action.

Do not average. An average hides exactly the weakness the report exists to surface. List gating weaknesses separately and above the scores: a gating weakness blocks a production-ready designation whatever the scores say.

Phase 10 — Implementation plan

Prioritised, in three bands: immediate (assets that establish the Foundation without changing production behaviour), pre-production (material gaps to resolve before the system is considered production-ready), post-launch (continuous-assurance improvements that do not block release).

Each action states: issue · consequence · proposed remedy · affected files · complexity (small/medium/large) · whether it changes runtime behaviour · whether human approval is required · whether it affects public Trust Wall claims.

Judgement principles

Implementation versus intention. A capability is implemented only when the operational path exists. An interface, type, mock, design document or dormant module is not sufficient.

Tests as evidence. Tests evidence intended and exercised behaviour; they do not prove production operation. Distinguish unit-tested · integration-tested · end-to-end tested · manually verified · production-observed.

Security claims. A framework default is not a control. Look for actual configuration and actual usage.

Privacy claims. Account for the whole path: collection, transmission, storage, access, retention, deletion, logs, telemetry, third-party processors. A gap anywhere in that path defeats the claim.

Compliance claims. Never infer legal or standards compliance from good engineering. Distinguish aligned with a control · partially implements a control · internally assessed · independently audited · certified.

Confidence. high direct implementation plus corroboration · medium credible but incomplete · low primarily inferred · unknown the repository cannot support a conclusion.

What the first run taught

Recorded because both lessons cost something to learn.

1. Verify against current code, never against your own earlier finding. On the first run, a control was live-tested and confirmed closed in the morning. By the afternoon, while pinning evidence for that same claim, the control was found to be absent — an unrelated merge had rewritten the file and dropped the enforcement. Nothing failed, because no test asserted any of it.

Had the Trust Wall been generated from commit history, or from the assessor's own verified-that-morning note, it would have published a false security claim about a live gap. Re-read the file at the commit you are assessing.

2. A security property not asserted by a test will eventually be removed by someone who does not know it matters. This is the single most useful sentence the process produced. An R-* rule is a backstop that catches a known-bad shape; only a test proves behaviour. When the assessment finds an unasserted security property, the finding is not "add a static check" — it is "add the test".