---
name: diretiva-editorial-workflow
type: directive
title: "Editorial Workflow — Wikifita"
description: "Mandatory editorial front for all wikifita content operations. Phases, rules, failure modes, content taxonomy, quality gates. Approved 2026-07-20."
tags: [editorial, workflow, okf, quality, directives]
timestamp: 2026-07-20
---

# Editorial Workflow — Wikifita

Mandatory editorial front for all wikifita content operations. Derived from empirical analysis of 70+ pages across 9 major operations. Every rule here was validated through practice — failures are documented, fixes are permanent.

---

## Authority

This directive sits under the wikifita authority contract:

1. Alefita's current instruction
2. Higher environment policies
3. CLAUDE.md / AGENTS.md
4. **This directive** + other directives
5. Verified project memory
6. Global profile and feedback

When this directive conflicts with agent defaults, this directive wins.

---

## Content Taxonomy

Every page belongs to one type. Type determines density, structure, and cross-reference patterns.

| Type | Examples | OKF type | Density | Structure |
|---|---|---|---|---|
| **Technical Reference** | packet-protocol, native-modules | `reference` | High — tables dominate, code samples, every line carries information | API-level detail, method signatures, data formats |
| **Architecture** | architecture, skia-rendering | `reference` | High — diagrams + prose | System design, component topology, data flow |
| **Post-Mortem** | code-quality, debugging-stories | `analysis` | Medium-high — metrics + narrative | What went wrong, what was learned, quantitative |
| **Narrative** | development-timeline, store-review-saga | `narrative` | Medium — flowing prose with structure | Chronological, human, pressure-driven |
| **People** | camdom-people, mikael-partner | `profile` | Low-medium — contextual, relational | Relationships, trust, personality, dynamics |
| **Forensic** | clickfix-attack-chain, clickfix-bddr | `analysis` | High — evidence-based, structured IOCs | MITRE mapping, detection rules, indicators |
| **Infrastructure** | fitalabs-infra, litellm-gateway | `reference` | High — config, stack, deployment | Architecture, env vars, containers |
| **Profile/Career** | camdom-career-profile, user_alefita | `profile` | Low-medium — identity, positioning | Skills, experience, market position |

**Rule:** Do not force uniform density across types. A profile page should not read like an API reference. A forensic page should not read like a narrative.

---

## Phase 0: Pre-Conditions

Before any editorial work begins.

| Check | How | Block? |
|---|---|---|
| Branch awareness | `git branch --show-current` | **YES** — confirm correct branch (main for public, personal for sensitive) |
| Source material identified | User specifies the authorized source and scope | **YES** — agents may discover and maintain material within that scope, with provenance |
| Canonical project identity | Verify the user-designated path with `pwd`, repository root, branch, remotes, and inventory | **YES** — do not edit a different checkout |
| Scope bounded | User says "integrate X" or "document Y" | SOFT — agent proposes, user confirms |
| pessoas/index.md consulted | Read before creating any person page | **YES** — prevents identity confusion (Mikael/Maso failure) |
| Existing wiki scanned | Check index.md for overlap/dedup | **YES** — prevents duplicate pages |

---

## Phase 1: Source Analysis

Inventory → Conceptual Atoms → Page Design

| Step | Action | Output |
|---|---|---|
| 1.1 | Read source material completely | Mental model of the domain |
| 1.2 | Identify conceptual atoms (discrete topics) | List of page candidates |
| 1.3 | Classify each atom by type | Type assignment per page |
| 1.4 | Map cross-references between atoms | Link graph |
| 1.5 | Identify hub page (domain overview) | Hub designation |
| 1.6 | Check existing wiki for overlap | Conflict resolution plan |

### The Monolithic Page Rule

**Never create a monolithic page.** If the source has 5+ distinct topics, it must become 5+ pages. The threshold test: if you can remove one topic without affecting the others, it's a separate page.

The fundamental unit is: **one concept, one page, dense with cross-references**. Not summaries. Not catch-all documents. Each page is a node in a knowledge graph.

---

## Phase 2: Generation

### Parallel vs Sequential

| Decision | Criteria | Approach |
|---|---|---|
| Sequential | < 5 pages, simple topics | One agent, one page at a time |
| Parallel | > 5 pages, independent topics | Subagents, one per page or cluster |
| Hybrid | Some pages depend on others | Create dependencies first, then parallel |

### Per-Page Checklist

- OKF frontmatter: `type`, `title`, `description` (English), `tags`, `timestamp`
- Content density appropriate to type (see Content Taxonomy)
- Cross-references to related pages using double-bracket bare filename format (NEVER path-based)
- Mermaid diagrams for topology, sequences, state machines
- Source attribution where relevant
- No secrets, no PII, no credentials
- snake_case filenames, no dates in names (unless contract-specific)

---

## Phase 3: Integration

Weaving pages into the knowledge graph.

| Step | Action | File |
|---|---|---|
| 3.1 | Update domain index or create section in root index | `index.md` |
| 3.2 | Add tags to tag index table | `index.md` |
| 3.3 | Cross-link with existing content in other domains | Existing + new pages |
| 3.4 | Log entry with semantic format | `log.md` |
| 3.5 | Update master memory index if applicable | `memorias/MEMORY.md` |
| 3.6 | Update people catalog if people were added | `pessoas/index.md` |

### Log Entry Format

```markdown
## [YYYY-MM-DD] <type> | <Title>

<One-line summary>

### Pages Created
- `page-name` — description

### Sources
- Source description

### Metrics
- Lines, page count, coverage
```

Type values: `feat`, `fix`, `refactor`, `ingest`, `update`, `create`

---

## Phase 4: Quality Gate

Audit → Fix → Audit → Commit

| Step | Action | Outcome |
|---|---|---|
| 4.1 | `uv run scripts/wikifita_audit.py` | First audit — expect some issues |
| 4.2 | Fix any issues | Corrections applied |
| 4.3 | Run audit again (no `--fix`) | Confirm PASS |
| 4.4 | `git add -A && git commit` | Pre-commit hook runs blocking audit |
| 4.5 | Confirm post-commit hook passed | Final verification |

**Rule:** Never commit until the audit passes twice (once with `--fix`, once without). The pre-commit hook is the final gate.

---

## Phase 5: Presentation (Optional)

When artifacts (HTML, documents) are needed.

- Visual identity from `diretivas/identidade-visual.md` (Anthropic dark mode)
- Use `mcp__cowork__create_artifact` for persistent artifacts
- Use `mcp__cowork__present_files` for one-off files
- Artifacts are **derived from** wiki content — wiki is source of truth
- Never maintain content in artifacts that should live in wiki pages
- Location: session outputs directory by default, project folder only if user requests

### Artifact Visual Identity

When creating HTML artifacts, apply the Anthropic dark mode system:

- **Palette:** bg `#171717`, surface `#232329`, warm `#d4a574`, green `#66bfa2`, red `#e8706a`
- **Typography:** Source Serif 4 (headings), Inter (body), JetBrains Mono (code)
- **Tables:** uppercase headers, letter-spacing 0.4px, `--text3` color, row hover `rgba(212,165,116,.04)`
- **Callouts:** `border-left: 3px solid var(--warm)`, background `rgba(212,165,116,.06)`
- **Metadata header:** Project, Author, Engine, Version, Date, Status
- **Footer:** Project name + version + date
- **Never:** neon gradients, AI slop, decorative animations, glowing borders

---

## Editorial Rules (Validated)

These rules proved themselves through practice across 70+ pages.

| # | Rule | Origin | Status |
|---|---|---|---|
| 1 | **One concept per page.** If you can remove a topic without affecting the rest, it's a separate page. | monolithic page rejection | VALIDATED |
| 2 | **Dense with cross-references.** Every page links to related pages. The wiki is a graph, not a list. | camdom section pattern | VALIDATED |
| 3 | **OKF frontmatter on every page.** type, title, description (EN), tags, timestamp. No exceptions. | audit enforcement | VALIDATED |
| 4 | **Authorized-scope, provenance-bound maintenance.** Agents may create or update content inside the scope Alefita authorized; they must not invent facts, fill gaps, or cross into another project or checkout. | autonomous-maintenance correction | VALIDATED |
| 5 | **Consult pessoas/index.md before creating person pages.** Prevents identity confusion. | Mikael/Maso failure | VALIDATED |
| 6 | **English for technical, Portuguese for personal.** Clear, no ambiguity. | translation session | VALIDATED |
| 7 | **Audit twice before committing.** Once with --fix, once without. | orphaned file experience | VALIDATED |
| 8 | **Check branch before writing.** Subagents don't inherit branch state. | branch contamination | VALIDATED |
| 9 | **Bare filename wikilink format only.** Path-based wikilinks break the auditor. | broken links | VALIDATED |
| 10 | **Each content type gets its own density.** Don't force uniformity across types. | density gradient analysis | PROPOSED |
| 11 | **Hub page per domain.** Every major section has a clear overview page that links outward. | topology analysis | PROPOSED |
| 12 | **Wiki is source of truth. Artifacts are derived.** Never maintain content in artifacts that should live in pages. | skill overlap analysis | PROPOSED |
| 13 | **Artifacts do not communicate with their author.** Public prose addresses its intended reader; status, questions, review requests and operational warnings stay in the active conversation. | fourth-wall artifact audit | VALIDATED |
| 14 | **Corrections produce final prose, not public errata.** Replace every affected claim and remove the invalid narrative unless claim evolution is the explicit research object. | ClickFix prediction-score refactor | VALIDATED |
| 15 | **Prefer structured sentences to Unicode dashes.** Use paragraphs and punctuation that preserve the actual semantic relationship. | final forensic editorial review | VALIDATED |
| 16 | **Significant authorized changes end in a validated semantic commit.** Report completion only after the commit exists; pushing remains separately authorized. | cross-turn Git-flow correction | VALIDATED |

---

## Failure Mode Taxonomy

| Failure Mode | Example | Defense |
|---|---|---|
| Monolithic page | camdom-development-context.md | Rule #1 + human review of page plan |
| Identity confusion | Mikael/Maso mix-up | Rule #5 + pessoas/index.md consultation |
| Branch contamination | Files on personal instead of main | Rule #8 + branch validation pre-step |
| Link format mismatch | Path-based wikilinks | Rule #9 + audit warning |
| Orphaned files | mikael-camdom.md (replaced but not deleted) | Audit orphan detection + cleanup step |
| Out-of-scope or unsupported maintenance | Agent creates or updates content outside the authorized scope, from the wrong checkout, or without inspectable provenance | Authority/scope check + live path verification + Rule #4 |
| Secret leakage | Credentials in wiki page | Phase 4 quality gate + manual review |
| Index drift | Pages exist but index doesn't list them | Audit index coverage check |
| Frontmatter inconsistency | Description in Portuguese | Audit validation + translation pass |
| Density mismatch | Profile with API-level detail | Rule #10 + type-based guidance |
| Fourth-wall artifact text | README asks its author to review, decide, revise or publish something | Rule #13 + explicit artifact-audience audit |
| Public correction theater | Final report explains an earlier wrong score instead of replacing it | Rule #14 + repository-wide claim refactor |
| Untracked completion state | Agent reports a finished change without a semantic commit | Rule #16 + pre-handoff Git verification |

---

## Wikilink Convention

All internal links use the bare filename format wrapped in double brackets, where the name matches the filename without extension.

Valid: double brackets around the bare filename, no paths, no directories.

Invalid: double brackets with path prefixes like `camdom/`, `wikifita/diretivas/`, or `pessoas/conexoes/`.

---

## Open Questions (Future Iteration)

Design decisions pending Alefita's input:

1. Should every page have a mandatory source attribution section?
2. Should domain indexes be separate files (`camdom/index.md`) or sections in root `index.md`?
3. Should stale content detection (timestamp-based) be added to the audit script?
4. Should personal branch content follow the same OKF standard or relaxed?
5. Should there be a "maximum pages per domain" heuristic before suggesting a split?

---

*This directive is alive. It evolves as the editorial practice evolves. Challenge it. Improve it. That is the protocol.*