tegwick
360c3b1de2
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>
4.7 KiB
id, name, artifact_type, description, version, tags
| id | name | artifact_type | description | version | tags | |||
|---|---|---|---|---|---|---|---|---|
| primer-authoring-rules-v1 | AuthoringRules | content | Comprehensive guidelines for writing effective InfoTech primers | 1.0.0 |
|
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:
- Definition
- Context
- Core Concepts
- Scope and Non-Scope
- Practical Implications
- Formal Standards and Authoritative Sources
- 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:
- 2–4 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:
**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:
- 600–1,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