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
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:
302
examples/content-generator/prepdr/AuthoringRules.md
Normal file
302
examples/content-generator/prepdr/AuthoringRules.md
Normal file
@@ -0,0 +1,302 @@
|
||||
AuthoringRules
|
||||
|
||||
*How to write effective primers*
|
||||
|
||||
## 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:
|
||||
|
||||
* 2–4 sentences maximum
|
||||
* Declarative, precise language
|
||||
* No metaphors, examples, or analogies
|
||||
* No historical narrative
|
||||
|
||||
Good:
|
||||
|
||||
> “OAuth 2.0 is an authorization framework that enables a third-party application to obtain limited access to an HTTP service on behalf of a resource owner.”
|
||||
|
||||
Bad:
|
||||
|
||||
> “OAuth is basically a way to let apps log in without sharing passwords.”
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
|
||||
Include:
|
||||
|
||||
* Typical environments
|
||||
* Architectural level (protocol, pattern, framework, etc.)
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
|
||||
Think: *“What must be true for this concept to exist?”*
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
|
||||
Examples of acceptable content:
|
||||
|
||||
* Design constraints
|
||||
* Operational complexity
|
||||
* Security or scalability implications
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
|
||||
Example:
|
||||
|
||||
> **OpenID Connect** – An identity layer built on top of OAuth 2.0.
|
||||
|
||||
---
|
||||
|
||||
## 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. Stability and Versioning
|
||||
|
||||
Primers are intended to be **stable reference artifacts**.
|
||||
|
||||
Rules:
|
||||
|
||||
* Do not chase trends
|
||||
* Avoid speculative content
|
||||
* Update only when:
|
||||
|
||||
* Standards change
|
||||
* Definitions evolve materially
|
||||
* Authoritative sources are superseded
|
||||
|
||||
When updating:
|
||||
|
||||
* Preserve conceptual continuity
|
||||
* Avoid rewriting without necessity
|
||||
|
||||
---
|
||||
|
||||
## 8. 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
|
||||
|
||||
---
|
||||
|
||||
## 9. 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
|
||||
|
||||
---
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
InfoTechPrimers are **not**:
|
||||
|
||||
* Documentation replacements
|
||||
* Training material
|
||||
* Opinionated best-practice guides
|
||||
* Tool comparisons
|
||||
|
||||
Those belong elsewhere.
|
||||
|
||||
---
|
||||
|
||||
### Version Note
|
||||
|
||||
This is **Primer Authoring Rules v0.1**.
|
||||
Expect tightening, not loosening, as real primers are written and validated.
|
||||
|
||||
|
||||
|
||||
xxx
|
||||
Reference in New Issue
Block a user