architect-explainer

Files (1)

• SKILL.md

SKILL.md (first lines)

# architect-explainer

**P0 — Code/System → Plain Decisions/Risks/Next Actions**
**Seal:** DITEMPA BUKAN DIBERI · 2026-03-27

---

## Purpose

Arif is a **geologist and sovereign architect**, not a coder. Every agent on this VPS must translate its technical work into language that lets Arif make sovereign decisions without having to read code.

The `architect-explainer` is not a summary. It is a **decision brief** — what changed, what it means, what can go wrong, and what Arif should decide next.

**Why this is P0:** The opencode catastrophe happened partly because opencode could not explain what it was about to do in terms Arif could challenge. An agent that speaks only code cannot be governed by a non-coder architect.

---

## Output Format — The Decision Brief

For every significant action, produce this structure:

```
═══════════════════════════════════════════════
 DECISION BRIEF — {timestamp}
═══════════════════════════════════════════════

WHAT: {One sentence. What was changed.}

WHY:  {One sentence. What problem this solves.}

WHAT CHANGED:
  • {file/component A}: {what changed} ({risk level})
  • {file/component B}: {what changed} ({risk level})

BLAST RADIUS (who this affects):
  • {service/component}: {how affected}
  • {user/stakeholder}: {how affected}

RISK: {LOW / MEDIUM / HIGH / CRITICAL}
  {One sentence explaining the risk.}

REVERSIBLE: {YES / NO / PARTIAL}
  {How to undo this, or why it cannot be undone.}

VERIFICATION: {How we know it worked. Not just "exit code 0."}

NEXT ACTION: {What happens next. Who does it.}

ARIF DECIDES:
  ○ PROCEED — I understand, do it
  ○ MODIFY  — Change X before proceeding
  ○ VETO     — Do not proceed
  ○ 888_HOLD — Escalate for deeper review

═══════════════════════════════════════════════
```

---

## Translation Rules

### Rule 1: Never say what the code does. Say what the code means for Arif.

❌ `"The migration adds an ALTER TABLE statement to add a NOT NULL constraint to the users table"`

✅ `"Your user database schema is changing. All existing users must have an email. If any user record is missing an email, the system will error until fixed. Backup exists. Safe to run."`

### Rule 2: Always state the risk in human terms.

❌ `"Docker compose restart may cause brief service interruption"`

✅ `"For 10-30 seconds, the MCP server will be unreachable. Any agent using it will pause and retry automatically."`

### Rule 3: State what could go wrong in concrete terms.

❌ `"Potential security implications"`

✅ `"If the new API key is exposed in logs, anyone can access your VPS services. Risk is LOW if .env is properly secured."`

### Rule 4: Give Arif a clear choice.

❌ `"The configuration change is ready"`

✅ `"Your choice: (A) Apply now — the change goes live immediately. (B) Test first — I run it in a sandbox. (C) Veto — I do nothing."`

### Rule 5: Flag the irreversible before it happens.

❌ `"git push --force will update the remote"`

✅ `"⚠️ CRITICAL: This OVERWRITES the remote branch. If the remote has work not on your local branch, it will be LOST. This cannot be undone without a backup. Do you confirm?"`

---

## Decision Brief Examples

### Example 1 — Git Force Push

```
WHAT: Overwrite remote main branch with local changes.

WHY:  Deploy new arifOS kernel module.

RISK: CRITICAL
  If remote has commits not in local, they are permanently lost.
  No recovery without a backup.

REVERSIBLE: NO
  Once pushed, cannot be recalled.

VERIFICATION: I will show you the diff before pushing.

ARIF DECIDES:
  ○ PROCEED — show me the diff first
  ○ MODIFY  — what needs changing
  ○ VETO    — do not push
```

### Example 2 — Docker Compose Restart

From ariffazil/arifOS, AGPL-3.0.

More from ariffazil/arifOS