This project demonstrates a pattern: treat a source repository + editor as a knowledge operating system. AI handles draft generation; humans handle architecture, truth maintenance, and iteration discipline. VS Code becomes the cockpit for fast diff review, structural refactors, and multi-file coherence—not just programming.
Core Idea
Source control + AI = accountable narrative evolution. Every improvement is a diff. You preserve provenance, can roll back hallucinations, and progressively harden soft claims into sourced facts.
1. Why Use an Editor for Non-Code Work?
- Atomic Changes: Small commits force thought modularity.
- Reviewable Diffs: Easier to spot semantic drift or sloppy generalizations.
- Link Integrity: Relative paths + search make cross-link audits trivial.
- Refactor Velocity: You can batch rename, reorganize folders, or template structures quickly.
2. The AI Collaboration Loop Inside VS Code
- Intent Frame: Open a scratch pad (e.g.,
dev/0-reqs/Reqs.md)—state goal, audience, scope, constraints. - Draft Generation: Ask AI for a structured outline (sections, bullet hierarchy, tables). Avoid prose first.
- Outline Critique: Manually tighten logic order; remove redundancy; insert evidence placeholders.
- Section Expansion: Expand 1–2 sections at a time—keep change sets small for clarity.
- Validation Pass: Highlight claims lacking sources; mark with TODO or [citation?] for later grounding.
- Hardening: Replace placeholder claims with sourced data; convert narrative lists into tables where useful.
- Cross-Linking: Add reciprocal links to related topics/articles to keep graph navigable.
3. Structural Conventions (Applied Here)
| Folder | Purpose | AI Role | Human Role |
|---|---|---|---|
/articles | Long-form narratives & patterns | Draft + restructure suggestions | Argument coherence, sourcing |
/topics | Stable conceptual overviews | First-pass taxonomy & summaries | Scope boundaries, updates |
/paths | Audience journeys | Persona bullet generation | Relevance pruning |
/dev | Meta governance docs | Checklist templating | Policy correctness |
4. Prompt Templates for Editing
Role: Senior editor improving coherence
Inputs: {section text}
Task: Identify logical gaps, redundancy, and unseen counterpoints. Return: bullet list of changes + improved revision.
Constraints: Preserve factual claims; flag unsourced statistics.
Role: Table normalizer Inputs: raw bullet list of metrics Task: Produce a markdown table with columns: Metric | Current Claim | Source Needed? (Y/N) | Suggested Source Type Constraint: Do not fabricate sources.
5. Guardrails Against AI Drift
- Diff Review: Never accept multi-hundred line monolithic changes—force segmentation.
- Claim Tagging: Use markers like
[verify]for ephemeral or speculative content. - Terminology Glossary: Centralize canonical definitions to avoid synonym dilution.
- Reciprocal Link Check: When adding a link from A → B ensure B references back if contextually relevant.
6. Turning Docs Into a Knowledge Graph
Consistent section IDs and anchors let you later ingest this repository into retrieval systems (vector stores) powering contextual AI answers. A curated, versioned dataset beats random web scraping for internal reliability.
7. Expansion: From Text to Light Automation
Once structure stabilizes, you can let AI propose simple scripts: link checkers, table normalizers, or citation gap reporters—still within VS Code. Human remains in approval loop; automation enforces hygiene.
8. Minimal Checklist
- State intent before drafting
- Outline → critique → expand
- Tag unsourced claims
- Convert dense paragraphs to tables/lists
- Reciprocal link pass
- Commit small diffs with descriptive messages