feat(examples): add content-generator example demonstrating Prompt Dependency Resolution
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled

This example demonstrates the full workflow of generating InfoTech primers
using MarkiTect's Prompt Dependency Resolution infrastructure.

Features demonstrated:
- Artifact creation and storage with content-based addressing
- PromptTemplate with @{macro} resolution across multiple spaces
- Automatic dependency tracking and graph construction
- Provenance tracing from outputs back to inputs
- Visualization export (Mermaid format)
- Incremental execution with change detection

Files added:
- generate_primers.py: Complete working example
- README.md: Quick start guide and architecture overview
- TUTORIAL.md: Comprehensive 500+ line tutorial
- templates/generate-primer.md: Template with macros
- artifacts/topics/: ETL and Microservices topic definitions
- artifacts/guidelines/: Authoring rules and research protocol
- prepdr/: Original manual system (preserved for reference)

Example output:
- Generates 2 primers (ETL, Microservices)
- Creates 8 artifacts across 4 information spaces
- Records 8 dependency edges in SQLite database
- Exports dependency graph visualization

Run with: cd examples/content-generator && python generate_primers.py

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-02-09 23:50:07 +01:00
parent 8f54a5509e
commit 360c3b1de2
14 changed files with 2501 additions and 0 deletions

View File

@@ -0,0 +1,200 @@
---
id: primer-authoring-rules-v1
name: AuthoringRules
artifact_type: content
description: Comprehensive guidelines for writing effective InfoTech primers
version: 1.0.0
tags:
- guidelines
- authoring
- quality-standards
---
# Primer Authoring Rules
**Status:** Draft
**Intended Audience:** Human authors and AI systems generating or validating primers
**Purpose:** Ensure primers are precise, stable, and suitable as shared context for humans and AI agents
---
## 1. What a Primer Is (Normative)
An **InfoTechPrimer** is a **short, structured reference document** that establishes a **shared understanding** of a specific IT term, standard, method, or concept.
A primer:
* Defines **what the topic is**
* Explains **where it fits**
* Clarifies **scope boundaries**
* Points to **authoritative sources**
A primer does **not**:
* Teach step-by-step usage
* Advocate tools or vendors
* Explore implementation details beyond what is normatively defined
---
## 2. Target Audience
Primers are written for:
* Humans with solid general IT knowledge
* Readers who are *not specialists* in the specific topic
* AI systems that consume structured context for reasoning and coding
Authors must assume:
* Conceptual literacy
* Familiarity with basic IT terminology
* No prior deep knowledge of the topic
---
## 3. Required Structure (Mandatory)
Every primer **MUST** contain the following sections **in this order**:
1. **Definition**
2. **Context**
3. **Core Concepts**
4. **Scope and Non-Scope**
5. **Practical Implications**
6. **Formal Standards and Authoritative Sources**
7. **Related Concepts**
No section may be omitted. Empty sections are not allowed.
---
## 4. Section Authoring Rules
### 4.1 Definition
**Purpose:** Establish an unambiguous baseline meaning.
Rules:
* 24 sentences maximum
* Declarative, precise language
* No metaphors, examples, or analogies
* No historical narrative
### 4.2 Context
**Purpose:** Position the concept within the IT landscape.
Rules:
* Describe the domain(s) the concept belongs to
* Explain *why it exists*, not *how to use it*
* Historical notes allowed only if they clarify intent or constraints
### 4.3 Core Concepts
**Purpose:** Identify the irreducible ideas that define the topic.
Rules:
* Bullet points only
* Each bullet describes one concept
* No nested lists
* Avoid redundancy with Definition
### 4.4 Scope and Non-Scope
**Purpose:** Prevent conceptual drift and misuse.
Rules:
* Explicitly list inclusions and exclusions
* Use parallel structure
* Address common misconceptions
Format:
```markdown
**In Scope**
- ...
**Out of Scope**
- ...
```
This section is **critical** for AI agent correctness.
### 4.5 Practical Implications
**Purpose:** Describe consequences of adopting or interacting with the concept.
Rules:
* Focus on effects, not instructions
* No step-by-step guidance
* Include tradeoffs where relevant
### 4.6 Formal Standards and Authoritative Sources
**Purpose:** Anchor the primer in canonical truth.
Rules:
* Prefer primary sources
* Include direct links
* Avoid blogs unless widely recognized and necessary
Acceptable sources:
* RFCs, W3C Recommendations
* ISO / IEC standards
* NIST publications
* Official specifications
* Foundational academic papers
At least **one** authoritative source is required.
### 4.7 Related Concepts
**Purpose:** Enable semantic navigation.
Rules:
* Short descriptions only (one line per concept)
* No deep explanations
* Avoid circular definitions
---
## 5. Language and Style Rules
Mandatory:
* Present tense
* Declarative sentences
* Neutral, technical tone
Avoid:
* First-person language ("we", "you")
* Rhetorical questions
* Marketing language
* Informal phrasing
* Emojis
---
## 6. Length Constraints
A primer should typically be:
* **6001,000 words total**
* Short enough to be read in one sitting
* Long enough to define boundaries clearly
Exceeding this range requires justification.
---
## 7. AI Optimization Rules (Explicit)
Authors **SHOULD**:
* Use consistent terminology
* Avoid synonyms for core terms once defined
* Prefer explicit over implicit assumptions
* State constraints clearly
Authors **MUST NOT**:
* Rely on context outside the document
* Assume tool- or framework-specific defaults
* Leave ambiguity where standards are explicit
---
## 8. Validation Criteria (Checklist)
A primer is valid if:
* [ ] All required sections are present
* [ ] Definition is precise and unambiguous
* [ ] Scope boundaries are explicit
* [ ] At least one authoritative source is linked
* [ ] No tutorial or marketing content exists
* [ ] Language follows declarative style rules