What is CRAFT and why was it created?
Quick Answer:
CRAFT (Configurable Reusable AI Framework Technology) is a structured framework that transforms chaotic AI conversations into efficient, consistent workflows by applying programming principles to natural language interactions, reducing token usage by 82-94% while maintaining perfect context across sessions.
Detailed Explanation:
CRAFT emerged from a fundamental observation about how we use AI today: despite impressive capabilities, we’re using AI inefficiently. Every chat session starts from zero. Every instruction requires verbose explanation. Every project detail needs constant repetition.
The framework solves three critical problems that plague traditional AI interactions:
CRAFT addresses these challenges by introducing five integrated components (Comments, Data Types, Variables, Functions, and Objects) that work together to create persistent, structured, efficient AI interactions. The framework doesn’t require the AI to change—instead, it provides a systematic way for humans to communicate with AI that leverages inherent capabilities while adding structure and memory.
Dramatic improvements are possible with CRAFT:
Example:
Traditional Approach (87 tokens):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TRADITIONAL: Verbose Repetition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“Please create a report for TechVentures Inc,
which is a SaaS company founded in 2018 that
provides cloud-based project management solutions
for enterprise clients with AI-powered task
prioritization and real-time collaboration
features.”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRAFT Approach (12 tokens):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRAFT: Efficient Reference
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Please create a report for
COMPANY_NAME using PRODUCT_DESCRIPTION)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Token reduction: 86% while maintaining perfect consistency.
Key Points:
Related Topics:
#AI->H::Status: (FAQ 3 complete – 3 more to go)
#AI->H::Note: (Continuing with FAQ 4 – Comments FAQ is longest, may take more space…)
How much of CRAFT do I need to adopt to see benefits?
Quick Answer:
Start with just 2-3 variables for information you repeatedly type, and one or two comment types to structure your requests—you’ll see immediate benefits without complexity, then add more components only when you encounter specific pain points that need solving.
Detailed Explanation:
The beauty of CRAFT is that you don’t need to adopt everything at once. The framework is designed for incremental adoption, where each small addition solves a specific frustration. Most users start with variables and comments, gaining 50-70% efficiency immediately, then gradually expand as needs grow.
Step 1: Stop Repeating Yourself
Identify the 3-5 pieces of information you type most often and turn them into variables.
Common Repetition Points:
Simple Starting Template:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Basic Variable Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Replace these with your actual information:
COMPANY_NAME = “TechVentures Inc”
PRODUCT_NAME = “TaskMaster Pro”
TARGET_AUDIENCE = “Small business owners,
non-technical”
BRAND_VOICE = “Professional but approachable,
avoid jargon”
#H->AI::Directive: (Create social media post about
new feature)
#H->AI::Context: (Use BRAND_VOICE for
TARGET_AUDIENCE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
That’s it. You’re using CRAFT. Copy this into your next AI conversation and reference these variables instead of retyping context.
Immediate Impact:
Step 2: Add Structure with Comments
Once comfortable with variables, add basic comment structure to clarify your requests.
Start with Just Two Comment Types:
#H->AI::Directive: – For clear commands
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Using Directive Comment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Analyze competitor pricing and
create comparison table)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: – For background information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Using Context Comment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: (We’re targeting enterprise
market, not SMB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This transforms rambling paragraphs into scannable, clear instructions that AI interprets more accurately.
Step 3: Define One Data Type
When you notice repeated structures, create your first data type.
Example: Customer Information
Instead of explaining customer details inconsistently:
Define once:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Customer Data Type
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Customer = DataType(“customer”,
fields=[“company_name”, “tier”,
“payment_schedule”, “support_level”])
enterprise_client = Customer(
company_name=”Acme Corp”,
tier=”Enterprise”,
payment_schedule=”monthly”,
support_level=”priority”
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Now every reference is consistent and complete.
Step 4: Create Your First Function
When you notice yourself giving the same multi-step instructions repeatedly, create a function.
Recognition Pattern:
“I’ve explained this process 3+ times the same way.”
Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Weekly Report Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Repeated instruction (150+ tokens each time):
“Generate weekly report with user growth, revenue,
churn rate, and support tickets. Calculate
week-over-week changes. Format as bullet points
with biggest changes first.”
Function (6 tokens to call):
def generate_weekly_report():
#H->AI::Directive: (Generate report for this
week)
#H->AI::Structure: (Bullet points, most
significant changes first)
#H->AI::Context: (Metrics: growth, revenue,
churn, support tickets)
#H->AI::Focus: (Calculate and highlight
week-over-week changes)Call with:
generate_weekly_report()
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 5: Objects (Only When Needed)
Objects make sense when you’re managing something with state that evolves over time.
When to Consider Objects:
Don’t Rush Objects:
Most users thrive on Variables + Comments + Functions for months before needing Objects. Only add them when the stateless approach creates genuine friction.
The Pain-Point Driven Approach:
Let problems guide your adoption:
Example Progression:
Day 1 – Absolute Minimum:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DAY 1: Starting Simple
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme Corp”
PRODUCT_NAME = “CloudSync Pro”
#H->AI::Directive: (Write email announcing new
feature)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 2 – Adding Context:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WEEK 2: Adding Context
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme Corp”
PRODUCT_NAME = “CloudSync Pro”
TARGET_AUDIENCE = “IT managers at mid-size
companies”
BRAND_VOICE = “Technical but accessible”
#H->AI::Directive: (Write email announcing new
feature)
#H->AI::Context: (Audience is TARGET_AUDIENCE)
#H->AI::Constraint: (Use BRAND_VOICE, keep under
200 words)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Month 1 – First Function:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MONTH 1: First Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All previous variables remain available…
def announce_feature(feature_name, key_benefit):
#H->AI::Directive: (Create announcement email
for {feature_name})
#H->AI::Context: (Emphasize {key_benefit} for
TARGET_AUDIENCE)
#H->AI::Structure: (Subject line + 3 paragraph
email)
#H->AI::Constraint: (Use BRAND_VOICE, under
200 words)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
Related Topics:
#AI->H::Status: (FAQ 1 complete – 5 more to go)
#AI->H::Note: (Continuing with FAQ 2…)
What do I need to start using CRAFT?
Quick Answer:
To start using CRAFT, you only need an AI chat interface (like
Claude, ChatGPT, or similar) and the ability to structure your
prompts using basic syntax—no special software, installation, or
technical setup required. You can begin with just variables and
comments in your very next conversation.
Detailed Explanation:
One of CRAFT’s key advantages is its simplicity of adoption.
Unlike traditional frameworks that require installations,
dependencies, or specialized environments, CRAFT works with AI
systems you’re already using. The framework is a communication
methodology, not a software package.
Minimal Starting Requirements:
CRAFT doesn’t modify the AI—it structures how you communicate
with it.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Basic CRAFT Syntax Patterns
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VARIABLE_NAME = “value”
#H->AI::Directive: (instruction)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If you can type these patterns, you can use CRAFT. No programming
experience required.
This file becomes your “project memory” that you paste into new
AI sessions.
The Four-File System (For Serious Implementation):
As you grow beyond basics, CRAFT uses a standardized four-file
structure:
File 1: Project Implementation File
* Contains your active Variables, Functions, Objects
* Filename pattern:
CFT-PROJ-[number]_[name]-v[version].txt
* Example: CFT-PROJ-025_CRAFT-ALPHA-PH5-v0825a3.txt
File 2: Conversation Continuity File
* Tracks session-to-session handoffs and decisions
* Filename pattern:
CFT-PROJ-[number]_AI-CHAT-HISTORY-v[version].txt
* Contains “Handoff” snapshots between sessions
File 3: Framework Specification File
* Defines CRAFT rules and standards (provided by CRAFT)
* Filename pattern: CFT-FWK-SPEC-v[version].txt
* You reference this, but don’t modify it
File 4: Framework Cookbook File
* Contains pre-built recipes and patterns (provided by
CRAFT)
* Filename pattern: CFT-FWK-COOKBK-v[version].txt
* Library of reusable solutions
What You DON’T Need:
* ❌ Programming environment or IDE
* ❌ Version control system (though Git is helpful for
teams)
* ❌ Special AI API access
* ❌ Command-line knowledge
* ❌ Server or hosting setup
* ❌ Database or storage system
Examples:
Absolute Beginner Start:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Starting CRAFT in Your Next Conversation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Open ChatGPT/Claude
Type:
COMPANY_NAME = “Acme Corp”
TAGLINE = “Innovation you can trust”
#H->AI::Directive: (Write LinkedIn post about our new
product)
#H->AI::Context: (Use COMPANY_NAME and TAGLINE)
Done. You’re using CRAFT.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Growing to Files:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Creating Your First CRAFT Project File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Create file: my-craft-project.txt
Contents:
COMPANY_NAME = “Acme Corp”
TAGLINE = “Innovation you can trust”
BRAND_VOICE = “Professional but approachable”
TARGET_AUDIENCE = “Small business owners”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* CRAFT requires no installation or special software—just
an AI chat interface
* Start immediately with variables and comments in your
current conversation
* A simple text file provides persistence across sessions
for growing projects
* The four-file system is for advanced users managing
complex, long-term projects
* No programming environment, APIs, or technical
infrastructure needed
* Adoption is incremental—start simple, grow as needed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Who should use CRAFT?
Quick Answer:
CRAFT is designed for anyone who regularly uses AI for work—from
solo entrepreneurs to enterprise teams—especially those
frustrated by repetitive prompts, inconsistent outputs, or lost
context between sessions, regardless of technical background.
Detailed Explanation:
CRAFT serves a broad spectrum of users because the problems it
solves are universal to AI interaction. While the framework uses
programming concepts, it’s designed to be accessible to
non-programmers while powerful enough for developers.
Primary User Profiles:
Solo Entrepreneurs and Small Business Owners
These users benefit most from CRAFT’s efficiency gains. When
you’re wearing multiple hats, eliminating repetitive AI prompts
and maintaining consistency becomes crucial:
* Marketing managers creating regular content who are
tired of re-explaining brand voice and product details
in every session
* Product managers documenting features, writing
requirements, and generating user stories with
consistent terminology
* Business owners managing customer communication,
proposals, and documentation who need professional
consistencyCRAFT Impact: Transforms 30-minute content creation sessions
into 5-minute structured commands. A solo founder using CRAFT
for blog posts, email campaigns, and social media reported
reclaiming 10+ hours per week.
Teams and Collaborators
When multiple people use AI for the same project, consistency
becomes critical. CRAFT provides shared vocabulary and
standardized processes:
* Development teams maintaining technical documentation
with consistent terminology across multiple
contributors
* Content teams ensuring brand voice remains uniform
regardless of who's creating the content
* Sales teams using standardized battlecards, proposals,
and outreach with consistent messagingCRAFT Impact: Eliminates the “everyone does it differently”
problem. Teams report 40-60% reduction in time spent
reconciling conflicting AI outputs or correcting
inconsistencies.
Enterprise Users Managing Complex Projects
Large-scale projects amplify every AI inefficiency. CRAFT’s
state management and structure become essential:
* Project managers tracking multi-phase initiatives
across multiple AI sessions spanning weeks or months
* Business analysts creating specifications, requirements
documents, and stakeholder reports with perfect
traceability
* Consultants managing multiple client engagements who
need client-specific context instantly availableCRAFT Impact: State preservation means projects can extend
across dozens of sessions without context loss. Enterprise
users report being able to maintain projects that previously
hit token limits or lost critical decisions.
Required Skills and Technical Background:
Non-Technical Users (No Programming Background)
You can start using CRAFT effectively by understanding basic
concepts:
* If you can write COMPANY_NAME = "Your Company", you
can use Variables
* If you can write #H->AI::Directive: (Do this thing),
you can use Comments
* The framework uses Python-like syntax precisely
because it's readable by non-programmersTechnical Users (Programming Background)
Developers find CRAFT immediately familiar since it mirrors
standard programming practices. They often:
* Rapidly build complex function libraries and object
hierarchies
* Create sophisticated data type systems with inheritance
and composition
* Design enterprise-scale frameworks for their entire
organizationWhen CRAFT May Not Be Necessary:
* One-off questions with no need for consistency or
memory
* Simple queries that require no business context
* Exploratory conversations where structure might feel
constraining
* Situations where the AI session will truly never
reference prior contextMost users discover that even “simple” use cases benefit from
basic CRAFT structure once they experience the consistency and
efficiency gains.
Examples:
Non-Technical User (Marketing Manager):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Simple Setup for Non-Technical Users
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BRAND_VOICE = “Professional but approachable, avoid
jargon”
TARGET_AUDIENCE = “Small business owners, non-technical”
#H->AI::Directive: (Write blog post about productivity
tips)
#H->AI::Context: (Use BRAND_VOICE for TARGET_AUDIENCE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Technical User (Developer):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Complex System for Technical Users
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class CampaignManager:
def init(self, audience_profile, budget,
constraints):
self.audience = self.analyze_profile(
audience_profile)
self.budget_tracker = BudgetAllocation(budget)
self.content_validator = ContentValidator(
constraints)
def generate_quarter_campaign(self):
#H->AI::Directive: (Generate Q2 campaign)
#H->AI::Context: (Use self.audience insights)
return structured_campaign_plan━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* CRAFT serves users from non-technical solo entrepreneurs
to enterprise development teams
* No programming experience required to start—basic
Variables and Comments provide immediate value
* Teams benefit from shared vocabulary and consistent
outputs across multiple contributors
* Enterprise users gain state management for complex,
multi-session projects
* Incremental adoption allows starting simple and growing
sophistication over time
* 86% of early users reported significant benefits within
the first week regardless of technical background
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What are the five core components of CRAFT?
Quick Answer:
CRAFT consists of five integrated components that work together:
Comments (structured communication), Data Types (information
containers), Variables (persistent memory), Functions (reusable
operations), and Objects (stateful entities)—each building upon
the others to create a complete framework.
Detailed Explanation:
CRAFT’s power comes not from individual components, but from how
they integrate and enhance each other. Think of them as
instruments in an orchestra—each plays its part, but the magic
happens when they harmonize.
Comments establish clear, bidirectional communication between
humans and AI. Instead of rambling instructions mixed with
context and constraints, CRAFT uses specific comment types:
Human to AI: Eight comment types including #H->AI::Directive:
(commands), #H->AI::Context: (background), #H->AI::Constraint:
(boundaries), and #H->AI::Structure: (format requirements).
AI to Human: Six comment types including #AI->H::Note:
(observations), #AI->H::Caution: (warnings), #AI->H::Question:
(clarifications), and #AI->H::Status: (progress updates).
This transforms a 100-token paragraph of mixed instructions into
clear, scannable, structured commands.
Data Types ensure AI interprets information consistently every
time. They extend beyond basic types (email, URL, date) to
include “business-native concepts”—the actual entities
businesses work with:
* Marketing.Campaign with fields for name, audience,
channels, budget, metrics
* Finance.Report with P&L, balance sheet, cash flow
specifications
* Product.Feature with specifications, dependencies,
status trackingNamespacing prevents confusion when different departments use
the same terms for different things (Marketing.Metric ≠
Finance.Metric ≠ Product.Metric).
Variables serve as “memory anchors”—stable reference points
that persist throughout conversations. They eliminate repetition
by storing information once and referencing it thereafter:
* Constants (UPPER_CASE) never change: COMPANY_NAME,
API_VERSION
* Dynamic variables (lower_case) update as needed:
current_project_phase, pending_tasks
* Multi-modal variables adapt content for different
audiences: PRODUCT_DESCRIPTION["technical"] vs
PRODUCT_DESCRIPTION["marketing"]This transforms 87-token context explanations into 12-token
variable references.
Functions wrap complex, multi-step processes into single,
reusable commands. They’re not simple aliases—they’re
intelligent operations that execute complete workflows:
Instead of repeatedly explaining a 7-step weekly report process
(156 tokens), you create generate_weekly_report() once and call
it thereafter (6 tokens). Functions accept parameters for
flexibility and can be composed together for complex workflows.
Objects represent the pinnacle of CRAFT’s architecture,
combining data and behavior into intelligent entities that
remember their history and evolve over time. Unlike stateless
functions, objects maintain identity:
A ProjectTracker object remembers its budget, tracks spending
over time, knows completion status, and builds historical
trends—transforming AI from an amnesia patient into a
knowledgeable assistant that recalls every project detail.
How They Work Together:
The integration follows a natural flow:
* Variables store your business context
* Data Types structure that context consistently
* Functions operate on typed data using stored variables
* Objects combine variables and functions into stateful
entities
* Comments orchestrate everything with clear instructions━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Five Components Working Together
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “TechVentures Inc”
TARGET_AUDIENCE = “enterprise SaaS buyers”
lead = Marketing.Lead(
company=”Acme Corp”,
contact=”Jane Smith, CTO”,
pain_points=[“manual processes”, “data silos”]
)
score = qualify_lead(lead)
opportunity = SalesOpportunity(lead)
opportunity.advance_stage()
#H->AI::Directive: (Create personalized outreach for
opportunity.lead)
#H->AI::Context: (Opportunity is in {opportunity.stage}
stage)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* Comments provide structured bidirectional communication
between human and AI
* Data Types ensure consistent interpretation with
business-native concepts
* Variables create persistent memory that eliminates
repetitive context-setting
* Functions encapsulate complex workflows into reusable,
parameterized operations
* Objects combine everything into stateful entities that
remember and evolve
* Each component enhances the others—the whole exceeds
the sum of its parts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What are CRAFT Comments and how do I use them?
Quick Answer:
CRAFT Comments are structured communication tags (like #H->AI::Directive: or #AI->H::Status:) that replace rambling instructions with clear, scannable, purpose-specific messages, creating bidirectional communication between you and the AI.
Detailed Explanation:
Comments transform chaotic AI interactions into organized conversations by establishing specific communication channels. Instead of mixing commands, context, constraints, and questions into paragraph-long prompts, CRAFT uses distinct comment types that tell the AI exactly what kind of information you’re providing.
The Problem Comments Solve:
Traditional Prompt (Before CRAFT):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BEFORE: Unstructured Rambling
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“I need you to analyze our competitor’s pricing
but don’t include any data from before 2024 and
make sure to focus on enterprise plans. Also, I
want you to be careful about making assumptions
and let me know if you’re not sure about
something. The context is that we’re preparing
for a board meeting next week.”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This mixes a directive, constraints, error handling, and context into one unstructured block. The AI must parse intent from mixed signals.
CRAFT Comment Structure (After):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AFTER: Clear Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Analyze competitor pricing for
enterprise plans)
#H->AI::Context: (Preparing for board meeting next
week)
#H->AI::Constraint: (Only include data from 2024
onwards)
#H->AI::OnError: (If data is uncertain, flag it
clearly)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Identical information, but structured for clarity. Each line has a clear purpose that AI interprets correctly.
Human-to-AI Comment Types:
1. #H->AI::Directive: – Explicit commands
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DIRECTIVE EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create quarterly sales report)
#H->AI::Directive: (Refactor this code for better
performance)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: Clear actions you want AI to take
2. #H->AI::Context: – Background information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONTEXT EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: (This is for a technical
audience)
#H->AI::Context: (Budget has been reduced by 20%
this quarter)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: Information that informs the response without being a command
3. #H->AI::Constraint: – Boundaries and limitations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONSTRAINT EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Constraint: (Keep response under 500
words)
#H->AI::Constraint: (Do not mention competitor
names directly)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: Hard limits that must not be violated
4. #H->AI::Question: – Direct inquiries
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
QUESTION EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (What’s the best approach for
this use case?)
#H->AI::Question: (Is this technically feasible
within our timeline?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: When you need AI’s analysis or recommendation
5. #H->AI::Focus: – Special attention areas
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FOCUS EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Focus: (Emphasize ROI and time-savings)
#H->AI::Focus: (Pay special attention to security
implications)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: Aspects requiring extra emphasis
6. #H->AI::Structure: – Output format requirements
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STRUCTURE EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Structure: (Format as bulleted list with
headers)
#H->AI::Structure: (Provide JSON output with
schema)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: How you want the response formatted
7. #H->AI::OnError: – Contingency plans
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ONERROR EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::OnError: (If data unavailable, explain
what’s missing)
#H->AI::OnError: (Rather than guess, ask for
clarification)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: How to handle uncertainty or inability to complete
8. #H->AI::EvaluateBy: – Success criteria
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EVALUATEBY EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::EvaluateBy: (Response accuracy and
completeness)
#H->AI::EvaluateBy: (Alignment with brand
guidelines)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: How AI should judge its own output quality
AI-to-Human Comment Types:
CRAFT is bidirectional—AI responds with structured feedback:
1. #AI->H::Note: – General observations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NOTE EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::Note: (This is the 4th similar request
this month)
#AI->H::Note: (Found 12 relevant sources)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2. #AI->H::Caution: – Warnings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CAUTION EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::Caution: (This approach may impact
performance)
#AI->H::Caution: (Insufficient data for confident
analysis)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3. #AI->H::Question: – Clarification requests
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI QUESTION EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::Question: (Which pricing tier should I
emphasize?)
#AI->H::Question: (Do you want technical details
or executive summary?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4. #AI->H::Status: – Progress updates
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STATUS EXAMPLES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::Status: (Analyzing 50 competitor websites)
#AI->H::Status: (Step 2 of 4 complete)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
5. #AI->H::RecommendMakingThisAFunction: – Optimization suggestions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FUNCTION RECOMMENDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::RecommendMakingThisAFunction: (You’ve
requested this report format 5 times)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
6. #AI->H::RequestingFeedback: – Explicit feedback requests
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FEEDBACK REQUEST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::RequestingFeedback: (Is this the level of
detail you need?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Feedback Loop in Action:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Complete Feedback Loop
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Human provides structured request:
#H->AI::Directive: (Generate weekly status report)
#H->AI::Context: (Include metrics from dashboard)
AI recognizes pattern:
#AI->H::Note: (This is the 4th identical request
this month)
#AI->H::RecommendMakingThisAFunction: (Create
generate_weekly_report() function)
#AI->H::Question: (Should I always include the
same metrics?)
Human refines based on AI feedback:
#H->AI::Directive: (Yes, create the function with
those standard metrics)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This creates intelligent conversation where AI actively helps optimize your workflow.
Example:
Complex Request Structured:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Multi-Comment Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Develop content strategy for
Q2 product launch)
#H->AI::Context: (Product is TaskMaster Pro 2.0,
targeting enterprise users)
#H->AI::Context: (Budget is $50K, timeline is 8
weeks)
#H->AI::Constraint: (Must work within existing
brand guidelines)
#H->AI::Focus: (Emphasize AI automation features
and time savings)
#H->AI::Structure: (Weekly breakdown with
deliverables and owners)
#H->AI::OnError: (If budget seems insufficient,
flag it with alternatives)
#H->AI::EvaluateBy: (Alignment with enterprise
buyer journey stages)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Clear, scannable, unambiguous—AI knows exactly what to do and how to do it.
Key Points:
What are Variables in CRAFT and why do I need them?
Quick Answer:
Variables are labeled containers that store information once (like COMPANY_NAME = “Acme Corp”) so you can reference it repeatedly without retyping, eliminating 82-94% of repetitive context-setting while ensuring perfect consistency across all AI interactions.
Detailed Explanation:
Variables solve one of the most frustrating aspects of AI conversations: endless repetition. Every traditional AI session starts with you explaining your company, your product, your target audience, your brand voice—over and over. Variables let you define this information once and reference it forever.
The Repetition Problem:
Imagine explaining your business in every AI session:
Session 1 (Monday):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MONDAY: Explaining Context Again
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“We’re TechVentures Inc, a B2B SaaS company
founded in 2018 providing cloud-based project
management with AI-powered task
prioritization…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 2 (Wednesday):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WEDNESDAY: Explaining Context Again
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“For context, TechVentures Inc is a B2B SaaS
platform that offers cloud-based project
management…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 3 (Friday):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FRIDAY: Explaining Context AGAIN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“TechVentures Inc (founded 2018) provides
AI-powered project management for enterprise
clients…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Three different phrasings, all consuming 50-100 tokens each, risking inconsistency. Variables eliminate this.
Variable Solution:
Define once:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DEFINE ONCE: Core Business Variables
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “TechVentures Inc”
COMPANY_TYPE = “B2B SaaS”
FOUNDING_YEAR = 2018
PRODUCT_DESCRIPTION = “Cloud-based project
management with AI-powered task prioritization”
TARGET_MARKET = “Enterprise companies with 500+
employees”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reference forever:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
REFERENCE FOREVER: Using Variables
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create investor update for
COMPANY_NAME)
#H->AI::Context: (Emphasize PRODUCT_DESCRIPTION
for TARGET_MARKET)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Result: 87 tokens become 12 tokens. 86% reduction.
Two Variable Types:
Constants (UPPER_CASE) – Information That Never Changes:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONSTANTS: Fixed Information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “TechVentures Inc”
FOUNDING_YEAR = 2018
API_VERSION = “v2.5”
BRAND_COLORS = [“#0066CC“, “#FF6B35“, “#F7F7F7“]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: Facts that remain stable (company name, founding date, API versions)
Dynamic Variables (lower_case) – Information That Updates:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DYNAMIC: Changing Information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
current_project_phase = “development”
# Was “planning” last week
pending_tasks = [“code review”, “deployment”,
“documentation”]
team_size = 12
# Updates when team grows
monthly_revenue = 125000
# Changes each month
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use for: Status, metrics, lists that evolve over time
The naming convention instantly signals whether a value is fixed or fluid, preventing accidental modifications to constants.
Token Efficiency Comparison:
Without Variables (87 tokens):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WITHOUT VARIABLES: Every Time
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“Please create a report for TechVentures Inc,
which is a SaaS company founded in 2018 that
provides cloud-based project management solutions
for enterprise clients with AI-powered task
prioritization and real-time collaboration
features.”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
With Variables (12 tokens):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WITH VARIABLES: Once Defined
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Please create a report for
COMPANY_NAME using PRODUCT_DESCRIPTION)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Over 10 similar requests:
Preventing Inconsistency:
Variables guarantee every reference uses identical information:
Problem Without Variables:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROBLEM: Inconsistent References
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Request 1: “Create ad copy for Task Master Pro”
# Extra space
Request 2: “Update docs for Taskmaster Pro”
# Missing capital
Request 3: “Send email about TaskMasterPro”
# No space
Result: Three different product names in your
materials.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Solution With Variables:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SOLUTION: Perfect Consistency
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRODUCT_NAME = “TaskMaster Pro”
Request 1: “Create ad copy for PRODUCT_NAME”
Request 2: “Update docs for PRODUCT_NAME”
Request 3: “Send email about PRODUCT_NAME”
Result: Perfect consistency, always
“TaskMaster Pro”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Multi-Modal Variables:
Context-aware variables adapt content for different audiences:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Multi-Modal Product Description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRODUCT_DESCRIPTION = {
“technical”: “Built on microservices
architecture using React frontend and Django
REST framework. Features Redis caching,
PostgreSQL persistence, Kubernetes
orchestration.”,
"marketing": "TaskMaster Pro revolutionizes
team collaboration. Our AI-powered platform
predicts bottlenecks and suggests task
redistribution for optimal performance.",
"investor": "B2B SaaS with 40% MoM growth,
serving 500+ enterprise clients. Proprietary
AI reduces project delays by 35%, NPS of 72,
net revenue retention of 115%."}
Usage depends on audience:
#H->AI::Directive: (Write blog post using
PRODUCT_DESCRIPTION[“marketing”])
#H->AI::Directive: (Create pitch deck using
PRODUCT_DESCRIPTION[“investor”])
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Same variable, different contexts—perfect for reaching diverse stakeholders.
Persistence Across Sessions:
Variables create true memory across AI conversations:
Monday’s Session:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MONDAY: Setting Project State
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROJECT_STATUS = “requirements gathering”
SPRINT_GOALS = [“user interviews”, “competitor
analysis”]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Wednesday’s Session:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WEDNESDAY: Variables Persist
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Variables persist – no re-explanation needed
#H->AI::Directive: (Update PROJECT_STATUS to
“design phase”)
#H->AI::Question: (What’s progress on
SPRINT_GOALS?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Friday’s Session:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FRIDAY: All Context Available
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All context still available
#H->AI::Directive: (Generate report showing
evolution from initial PROJECT_STATUS)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This transforms AI from an amnesia patient into a knowledgeable assistant.
Example:
Traditional Approach (Every Session):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TRADITIONAL: Repeat Every Time
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“For context, I’m the CTO at a startup with 15
engineers. We’re building a fintech app targeting
millennials. Our tech stack is React Native,
Node.js, and PostgreSQL. We’re in Series A
fundraising stage.”
Token cost per session: ~60 tokens
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRAFT Variables (Define Once):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRAFT: Define Once, Use Forever
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MY_ROLE = “CTO”
COMPANY_SIZE = “15 engineers”
PRODUCT_TYPE = “Fintech mobile app”
TARGET_AUDIENCE = “Millennials”
TECH_STACK = [“React Native”, “Node.js”,
“PostgreSQL”]
FUNDING_STAGE = “Series A”
Every subsequent session:
#H->AI::Context: (I’m the MY_ROLE at a company
with COMPANY_SIZE)
#H->AI::Context: (Building PRODUCT_TYPE for
TARGET_AUDIENCE)
Token cost per session: ~15 tokens (75% reduction)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Over 20 sessions: Save 900 tokens
Key Points:
What are Data Types in CRAFT?
Quick Answer:
Data Types are structured templates that ensure AI interprets complex information consistently every time by defining exactly what fields and format to expect (like a Marketing.Campaign with name, audience, channels, and budget), eliminating ambiguity and ensuring completeness.
Detailed Explanation:
When you tell an AI about a “campaign,” what exactly do you mean? A marketing campaign? Political campaign? Military campaign? What information should it include? Without structure, AI must guess from context—and sometimes guesses wrong. Data Types solve this by providing explicit structure and business-native concepts.
The Ambiguity Problem:
Unstructured Approach:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UNSTRUCTURED: Ambiguous Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“Create a campaign for our new product launch
with a budget of 50k targeting tech professionals
through social media.”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Questions this raises:
AI fills in gaps based on assumptions, which may not match your expectations.
Structured Data Type Approach:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STRUCTURED: Complete Specification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
campaign = Marketing.Campaign(
name=”Q1 Product Launch”,
audience=”tech professionals”,
channels=[“LinkedIn”, “Twitter”, “Reddit”],
budget=50000,
budget_allocation={
“LinkedIn”: 25000,
“Twitter”: 15000,
“Reddit”: 10000
},
timeline=”8 weeks”,
content_types=[
“blog posts”,
“social videos”,
“infographics”
],
success_metrics=[
“impressions”,
“CTR”,
“conversions”,
“CAC”
]
)
#H->AI::Directive: (Develop campaign plan using
campaign details above)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Complete clarity. No ambiguity. All information explicitly provided.
Core Types vs Business-Native Concepts:
Basic Types AI Already Understands:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BASIC TYPES: Leveraging AI Knowledge
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Email = DataType(“email_address”)
URL = DataType(“web_address”)
Date = DataType(“calendar_date”)
PhoneNumber = DataType(“phone_number”)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
These leverage AI’s inherent understanding while adding validation and structure.
Business-Native Types That Reflect Real Work:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BUSINESS TYPES: Real-World Entities
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Campaign = DataType(“marketing_campaign”,
required_fields=[“name”, “audience”,
“channels”, “budget”],
optional_fields=[“timeline”, “success_metrics”,
“content_types”]
)
UserStory = DataType(“requirement”,
required_fields=[“as_a”, “i_want”, “so_that”],
optional_fields=[“acceptance_criteria”,
“priority”, “estimate”]
)
Invoice = DataType(“financial_document”,
required_fields=[“invoice_number”, “amount”,
“due_date”, “vendor”],
optional_fields=[“payment_terms”, “line_items”,
“notes”, “PO_number”]
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The innovation: AI systems already understand these concepts generally. CRAFT adds structure to ensure critical information is never missed while allowing flexibility for additional details.
Required vs Optional Fields:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Customer with Required/Optional
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Customer = DataType(“customer_record”,
required_fields=[
“company_name”, # Must have
“tier”, # Must have
“mrr” # Must have
],
optional_fields=[
“notes”, # Nice to have
“renewal_date”, # If applicable
“health_score” # If calculated
]
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This ensures you never forget critical information while allowing flexibility for additional context.
Domain-Specific Types with Namespacing:
Different departments often use the same terms for different things. Namespacing prevents catastrophic confusion:
Marketing Namespace:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MARKETING NAMESPACE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Marketing.Campaign
# Social media, content, advertising
Marketing.Metric
# Conversion rates, CAC, engagement,
# impressions
Marketing.Lead
# Contact info, source, lead score, stage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Finance Namespace:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FINANCE NAMESPACE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Finance.Metric
# Revenue, burn rate, runway, EBITDA
Finance.Report
# P&L, balance sheet, cash flow statement
Finance.Forecast
# Projections, scenarios, assumptions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Product Namespace:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PRODUCT NAMESPACE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Product.Metric
# Usage statistics, feature adoption, DAU/MAU
Product.Feature
# Specifications, dependencies, status, owner
Product.Roadmap
# Milestones, priorities, timelines, releases
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Critical Distinction:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NAMESPACING PREVENTS CONFUSION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Marketing.Metric ≠ Finance.Metric ≠ Product.Metric
#H->AI::Directive: (Generate report on
Marketing.Metric for Q1)
AI knows exactly: Marketing conversion rates, NOT
financial metrics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How AI Interprets Typed vs Untyped Data:
Untyped Approach:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UNTYPED: AI Must Guess
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“Track our metrics”
AI must guess: Marketing metrics? Financial
metrics? Product metrics? All of them?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Typed Approach:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TYPED: AI Knows Precisely
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Generate report on
Marketing.Metric for Q1)
#H->AI::Focus: (Emphasize
Marketing.Metric.conversion_rate trends)
AI knows precisely: Marketing conversion rates,
specific focus on conversion trends.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Preventing Missing Information:
Data Types act as checklists ensuring completeness:
Without Types (Information Often Missing):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WITHOUT TYPES: Easy to Forget Things
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
“Create a customer record for Acme Corp”
Might forget: tier, MRR, contract date, support
level
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
With Types (Enforced Completeness):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WITH TYPES: Completeness Enforced
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
new_customer = Customer(
company_name=”Acme Corp”,
tier=, # Required – can’t skip
mrr=, # Required – can’t skip
contract_date=, # Required – can’t skip
support_level= # Optional but prompted
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The structure itself prevents oversight.
Example:
Complex Business Entity – Product Feature:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Complete Product Feature Definition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Feature = DataType(“product_feature”,
required_fields=[
“feature_name”,
“description”,
“target_release”,
“owner”
],
optional_fields=[
“dependencies”,
“technical_specs”,
“user_stories”,
“design_mockups”
]
)
new_feature = Product.Feature(
feature_name=”Real-time Collaboration”,
description=”Allow multiple users to edit
simultaneously”,
target_release=”Q2 2024″,
owner=”Engineering Team”,
dependencies=[
“WebSocket infrastructure”,
“Conflict resolution system”
],
user_stories=[
“As a team member, I want to see edits in
real-time…”
]
)
#H->AI::Directive: (Create technical specification
for new_feature)
#H->AI::Context: (Consider new_feature.dependencies
for implementation)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI receives complete, structured information—no guesswork required.
Key Points:
What are Functions in CRAFT?
Quick Answer:
Functions are reusable, multi-step operations that wrap complex
business logic into single commands (like generate_weekly_report()
instead of explaining the same 7-step process repeatedly),
reducing 150+ token instructions to 5-10 token function calls
while ensuring consistency.
Detailed Explanation:
Functions solve the problem of repetitive, complex instructions.
If you find yourself giving AI the same multi-step process over
and over—analyzing competitors, generating reports, creating
content templates—you need a function. Functions encapsulate
your business logic into single, reusable commands.
The Repetition Problem:
How many times have you given AI nearly identical instructions?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Repetitive Instructions Without Functions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 1:
“I need you to analyze this competitor. First, research
their pricing structure. Then compare their features with
ours. Create a comparison matrix. Identify where we win
and where they win. Focus especially on enterprise
features since that’s our target. Format as a table with
clear headers.”
Token cost: 156 tokens
Week 2:
“Can you analyze another competitor? Look at their
pricing and features, compare with our offering, make a
matrix showing strengths/weaknesses for each, emphasize
enterprise capabilities, use table format.”
Token cost: 142 tokens
Week 3:
“Competitor analysis time again. Pricing and feature
comparison needed, matrix format, highlight enterprise
aspects, show where each of us is stronger…”
Token cost: 135 tokens
Same process, slightly different wording, burning tokens
and risking inconsistency.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Function Solution:
Define once:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Function Definition – Define Once
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def analyze_competitor(competitor_name,
focus_area=”enterprise”):
“””
Performs comprehensive competitor analysis with
comparison matrix
“””
#H->AI::Directive: (Research {competitor_name}’s
pricing and features)
#H->AI::Directive: (Compare with our
PRODUCT_FEATURES)
#H->AI::Structure: (Create comparison matrix showing
wins/losses)
#H->AI::Focus: (Emphasize {focus_area} capabilities)
#H->AI::Context: (Target market is TARGET_AUDIENCE)
return structured_analysis━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use forever:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Function Usage – Use Forever
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
analyze_competitor(“TechCorp”)
analyze_competitor(“CloudSoft”, “SMB”)
analyze_competitor(“DataFlow”)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Token savings per use: 90-95%
Functions vs Simple Aliases:
This distinction is critical—functions aren’t just shorthand:
Simple Alias (Just Renames):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Simple Alias – Not a Real Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
comp_analysis = “competitor analysis”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This is just a variable. No logic, no process, no
intelligence.
Real Function (Executes Process):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Real Function – Executes Complete Workflow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def analyze_competitor(competitor_name,
aspects=[“pricing”, “features”]):
“””
Performs actual multi-step analysis workflow
“””
#H->AI::Directive: (Research {competitor_name}’s
{aspects})
#H->AI::Structure: (Create comparison matrix)
#H->AI::Context: (Use our PRODUCT_FEATURES for
baseline)
#H->AI::OnError: (If data unavailable, note gaps
clearly)
return structured_analysis━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This executes a complete workflow with error handling and
context.
Simple Functions for Common Tasks:
Start with functions for your most repetitive activities:
Weekly Report Generation:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Weekly Report Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def generate_weekly_report(week_ending,
highlight_threshold=10):
“””
Automated weekly metrics report with trend analysis
“””
#H->AI::Directive: (Generate report for week ending
{week_ending})
#H->AI::Structure: (Bullet points, most important
changes first)
#H->AI::Context: (Metrics: user growth, revenue,
churn, support tickets)
#H->AI::Focus: (Highlight changes over
{highlight_threshold}%)
#H->AI::Structure: (Add summary paragraph with key
insights)
return {"report": report_content,
"subject": email_subject}report = generate_weekly_report(“2024-01-28”)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Job Posting Creation:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Job Posting Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def create_job_posting(role, level, requirements):
“””
Generates complete job posting with company standards
“””
#H->AI::Context: (Use COMPANY_CULTURE and
BENEFITS_PACKAGE)
#H->AI::Structure: (Include: role summary,
responsibilities, requirements, benefits)
#H->AI::Constraint: (Match BRAND_VOICE, avoid
discrimination risk language)
return formatted_postingengineer_role = create_job_posting(
“Software Engineer”,
“Senior”,
[“5+ years Python”, “AWS experience”]
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prospect Outreach:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Prospect Outreach Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def prospect_outreach(company, contact_role, pain_point):
“””
Creates personalized cold outreach email
“””
#H->AI::Directive: (Draft outreach to {contact_role}
at {company})
#H->AI::Focus: (Address {pain_point} with our
PRODUCT_DESCRIPTION)
#H->AI::Constraint: (Keep under 150 words, no sales
jargon)
#H->AI::Context: (Reference relevant case study if
applicable)
return email_draftemail = prospect_outreach(
“Acme Corp”,
“VP Engineering”,
“deployment bottlenecks”
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Function Parameters for Flexibility:
Parameters make functions adaptable while maintaining
consistency:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Flexible Content Generation Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def generate_content(
topic, # Required: what to write about
content_type=”blog”, # Optional: defaults to blog
length=”medium”, # Optional: short/medium/long
tone=”professional”, # Optional: voice adjustment
include_cta=True # Optional: call-to-action
):
“””
Flexible content generation for any marketing need
“””
# Map length to approximate word counts
word_counts = {
“short”: 300,
“medium”: 800,
“long”: 1500
}
#H->AI::Directive: (Create {content_type} about
{topic})
#H->AI::Structure: (Length: {length}, approximately
{word_counts[length]} words)
#H->AI::Context: (Maintain {tone} tone throughout)
#H->AI::Context: (Target audience is
TARGET_AUDIENCE)
if include_cta:
#H->AI::Structure: (End with compelling
call-to-action)
return contentblog = generate_content(
“AI trends”,
content_type=”blog”,
tone=”conversational”
)
email = generate_content(
“AI trends”,
content_type=”email”,
length=”short”
)
whitepaper = generate_content(
“AI trends”,
content_type=”whitepaper”,
tone=”academic”,
length=”long”
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Composed Functions for Complex Workflows:
Functions become powerful when combined:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Composed Functions for Product Launch
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def launch_product(product_details):
“””
Complete product launch workflow orchestrating
multiple functions
“””
# Each function handles its specialized task
messaging = create_messaging(product_details)
content = generate_launch_content(messaging)
campaign = setup_campaign(content)
tracking = configure_analytics(campaign)
return LaunchPackage(
messaging, content, campaign, tracking
)def create_messaging(details):
#H->AI::Directive: (Create positioning and key
messages for {details.name})
#H->AI::Context: (Use PRODUCT_POSITIONING and
TARGET_AUDIENCE)
return messaging_guide
def generate_launch_content(messaging):
#H->AI::Directive: (Create blog, email, social posts
from messaging guide)
#H->AI::Structure: (Full content suite for
multi-channel launch)
return content_suite
def setup_campaign(content):
#H->AI::Directive: (Structure 8-week multi-channel
campaign using content)
#H->AI::Context: (Budget is MARKETING_BUDGET,
channels are MARKETING_CHANNELS)
return campaign_plan
launch = launch_product(product_v2_details)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
When to Create a Function:
The “Rule of Three”:
If you’ve given the same instructions 3+ times with minimal
variation, create a function.
Recognition Patterns:
* "I need to do that report again…"
* "Same analysis, different competitor…"
* "Let's create another version of…"These phrases signal function opportunities.
Example:
Before Functions:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Before Creating a Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Every Monday morning, 150+ token explanation:
“Generate our weekly status report. Start by gathering
key metrics from the dashboard – user growth, revenue,
churn rate, and support tickets. Calculate
week-over-week changes for each. Format as bullet points
with the most significant changes at the top. Add a
summary paragraph highlighting key insights. Make sure
to flag anything that changed by more than 10%.”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
After Creating Function:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: After Creating a Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def generate_weekly_report():
#H->AI::Directive: (Generate weekly status report)
#H->AI::Context: (Metrics: user_growth, revenue,
churn, support_tickets)
#H->AI::Structure: (Bullet points, biggest changes
first + summary paragraph)
#H->AI::Focus: (Flag changes > 10%)
generate_weekly_report()
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Over 52 weeks:
* Without function: 7,800 tokens
* With function: ~350 tokens (first definition +
51 calls)
* Savings: 7,450 tokens (95%)Key Points:
* Functions encapsulate complex, multi-step processes
into single, reusable commands
* Not aliases—they execute actual workflows with logic,
context, and error handling
* Parameters provide flexibility while maintaining
consistency (same function, different contexts)
* Create functions after repeating similar instructions
3+ times (Rule of Three)
* Composed functions orchestrate complex workflows by
combining simpler functions
* Typical savings: 90-95% token reduction per use after
initial definition
* Transform 150-token instructions into 5-10 token
function calls
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Functions are reusable, multi-step operations that wrap complex business logic into single commands (like generate_weekly_report() instead of explaining the same 7-step process repeatedly), reducing 150+ token instructions to 5-10 token function calls while ensuring consistency.
Detailed Explanation:
Functions solve the problem of repetitive, complex instructions. If you find yourself giving AI the same multi-step process over and over—analyzing competitors, generating reports, creating content templates—you need a function. Functions encapsulate your business logic into single, reusable commands.
The Repetition Problem:
How many times have you given AI nearly identical instructions?
Week 1:
"I need you to analyze this competitor. First, research their pricing structure.Then compare their features with ours. Create a comparison matrix. Identifywhere we win and where they win. Focus especially on enterprise featuressince that's our target. Format as a table with clear headers."
Token cost: 156 tokens
Week 2:
"Can you analyze another competitor? Look at their pricing and features,compare with our offering, make a matrix showing strengths/weaknessesfor each, emphasize enterprise capabilities, use table format."
Token cost: 142 tokens
Week 3:
"Competitor analysis time again. Pricing and feature comparison needed,matrix format, highlight enterprise aspects, show where each of us is stronger..."
Token cost: 135 tokens
Same process, slightly different wording, burning tokens and risking inconsistency.
Function Solution:
Define once:
defanalyze_competitor(competitor_name, focus_area="enterprise"):"""Performs comprehensive competitor analysis with comparison matrix"""#H->AI::Directive: (Research {competitor_name}'s pricing and features)#H->AI::Directive: (Compare with our PRODUCT_FEATURES)#H->AI::Structure: (Create comparison matrix showing wins/losses)#H->AI::Focus: (Emphasize {focus_area} capabilities)#H->AI::Context: (Target market is TARGET_AUDIENCE)returnstructured_analysis
Use forever:
analyze_competitor("TechCorp")# 6 tokensanalyze_competitor("CloudSoft","SMB")# 8 tokensanalyze_competitor("DataFlow")# 6 tokens
Token savings per use: 90-95%
Functions vs Simple Aliases:
This distinction is critical—functions aren’t just shorthand:
Simple Alias (Just Renames):
comp_analysis="competitor analysis"# Just replaces text
This is just a variable. No logic, no process, no intelligence.
Real Function (Executes Process):
defanalyze_competitor(competitor_name, aspects=["pricing","features"]):"""Performs actual multi-step analysis workflow"""#H->AI::Directive: (Research {competitor_name}'s {aspects})#H->AI::Structure: (Create comparison matrix)#H->AI::Context: (Use our PRODUCT_FEATURES for baseline)#H->AI::OnError: (If data unavailable, note gaps clearly)returnstructured_analysis
This executes a complete workflow with error handling and context.
Simple Functions for Common Tasks:
Start with functions for your most repetitive activities:
Weekly Report Generation:
defgenerate_weekly_report(week_ending, highlight_threshold=10):"""Automated weekly metrics report with trend analysis"""#H->AI::Directive: (Generate report for week ending {week_ending})#H->AI::Structure: (Bullet points, most important changes first)#H->AI::Context: (Metrics: user growth, revenue, churn, support tickets)#H->AI::Focus: (Highlight changes over {highlight_threshold}%)#H->AI::Structure: (Add summary paragraph with key insights)return{"report": report_content,"subject": email_subject}# Usage:report = generate_weekly_report("2024-01-28")
Job Posting Creation:
defcreate_job_posting(role, level, requirements):"""Generates complete job posting with company standards"""#H->AI::Context: (Use COMPANY_CULTURE and BENEFITS_PACKAGE)#H->AI::Structure: (Include: role summary, responsibilities, requirements, benefits)#H->AI::Constraint: (Match BRAND_VOICE, avoid discrimination risk language)returnformatted_posting# Usage:engineer_role=create_job_posting("Software Engineer","Senior",["5+ years Python","AWS experience"])
Prospect Outreach:
defprospect_outreach(company, contact_role, pain_point):"""Creates personalized cold outreach email"""#H->AI::Directive: (Draft outreach to {contact_role} at {company})#H->AI::Focus: (Address {pain_point} with our PRODUCT_DESCRIPTION)#H->AI::Constraint: (Keep under 150 words, no sales jargon)#H->AI::Context: (Reference relevant case study if applicable)returnemail_draft# Usage:=prospect_outreach("Acme Corp","VP Engineering","deployment bottlenecks")
Function Parameters for Flexibility:
Parameters make functions adaptable while maintaining consistency:
defgenerate_content( topic,# Required: what to write aboutcontent_type="blog",# Optional: defaults to bloglength="medium",# Optional: short/medium/longtone="professional",# Optional: voice adjustmentinclude_cta=True# Optional: call-to-action):"""Flexible content generation for any marketing need"""# Map length to approximate word countsword_counts ={"short":300,"medium":800,"long":1500}#H->AI::Directive: (Create {content_type} about {topic})#H->AI::Structure: (Length: {length}, approximately {word_counts[length]} words)#H->AI::Context: (Maintain {tone} tone throughout)#H->AI::Context: (Target audience is TARGET_AUDIENCE)ifinclude_cta:#H->AI::Structure: (End with compelling call-to-action)returncontent# Same function, infinitely flexible:blog = generate_content("AI trends", content_type="blog", tone="conversational")email = generate_content("AI trends", content_type="email", length="short")whitepaper = generate_content("AI trends", content_type="whitepaper", tone="academic", length="long")
Composed Functions for Complex Workflows:
Functions become powerful when combined:
deflaunch_product(product_details):"""Complete product launch workflow orchestrating multiple functions"""# Each function handles its specialized taskmessaging = create_messaging(product_details) content = generate_launch_content(messaging) campaign = setup_campaign(content) tracking = configure_analytics(campaign)return LaunchPackage(messaging, content, campaign, tracking)defcreate_messaging(details):#H->AI::Directive: (Create positioning and key messages for {details.name})#H->AI::Context: (Use PRODUCT_POSITIONING and TARGET_AUDIENCE)return messaging_guidedefgenerate_launch_content(messaging):#H->AI::Directive: (Create blog, email, social posts from messaging guide)#H->AI::Structure: (Full content suite for multi-channel launch)return content_suitedefsetup_campaign(content):#H->AI::Directive: (Structure 8-week multi-channel campaign using content)#H->AI::Context: (Budget is MARKETING_BUDGET, channels are MARKETING_CHANNELS)return campaign_plan# One command orchestrates entire product launch:launch = launch_product(product_v2_details)
When to Create a Function:
The “Rule of Three”:
If you’ve given the same instructions 3+ times with minimal variation, create a function.
Recognition Patterns:
These phrases signal function opportunities.
Example:
Before Functions:
Every Monday morning, 150+ token explanation:"Generate our weekly status report. Start by gathering key metrics fromthe dashboard - user growth, revenue, churn rate, and support tickets.Calculate week-over-week changes for each. Format as bullet points withthe most significant changes at the top. Add a summary paragraph highlightingkey insights. Make sure to flag anything that changed by more than 10%."
After Creating Function:
defgenerate_weekly_report():#H->AI::Directive: (Generate weekly status report)#H->AI::Context: (Metrics: user_growth, revenue, churn, support_tickets)#H->AI::Structure: (Bullet points, biggest changes first + summary paragraph)#H->AI::Focus: (Flag changes > 10%)# Every Monday morning, 6 tokens:generate_weekly_report()
Over 52 weeks:
Key Points:
Related Topics:
What are Objects in CRAFT?
Quick Answer:
Objects are stateful entities that remember their history and
evolve over time (like a ProjectTracker that knows its budget,
spending, milestones, and trends), transforming AI from an
amnesia patient with no memory into a knowledgeable assistant
that maintains context across unlimited sessions.
Detailed Explanation:
Objects represent the pinnacle of CRAFT’s architecture,
combining data and behavior into intelligent entities that
persist and evolve. While functions perform actions, objects
maintain identity, remember their past, and build history—
fundamentally changing how AI assists with long-term work.
Stateless vs Stateful:
Traditional AI interactions are stateless—each conversation
starts fresh:
Stateless Interaction (Traditional AI):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Stateless AI – No Memory Between Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Monday: “What’s the project status?”
AI: “I don’t have information about any project.”
Wednesday: “What’s the project status?”
AI: “I don’t have information about any project.”
Friday: “What’s the project status?”
AI: “I don’t have information about any project.”
It’s like working with someone who has amnesia between
every meeting.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stateful Interaction (With Objects):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Stateful AI with Objects – Persistent Memory
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Monday:
project = ProjectTracker(“Website Redesign”,
budget=50000)
Wednesday: “What’s the project status?”
AI: “Website Redesign is in development phase. 3 of 5
milestones complete. $18,000 spent of $50,000 budget
(36%). On track for deadline.”
Friday: “What’s the project health trend?”
AI: “Budget health improving—was 40% spent at milestone
2, now 36% at milestone 3. Team velocity increased 15%
this week. Status: green.”
The object remembers everything and builds history
automatically.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Objects vs Functions: The Key Difference:
Function (Performs Task):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Function – Must Provide All Info Each Time
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def calculate_project_health(milestones, budget, spent,
timeline):
“””
Calculates health score based on inputs provided
each time
“””
return health_score
calculate_project_health(
[m1, m2, m3],
50000,
18000,
“Q1-2024”
)
The function needs all information supplied with every
call.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Object (Maintains Ongoing State):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object – Remembers Its Own State
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class ProjectTracker:
def init(self, name, budget):
self.name = name
self.budget = budget
self.spent = 0
self.status = “planning”
self.milestones = {}
self.health_history = []
def update_spent(self, amount):
self.spent += amount
self.check_budget_health()
def check_budget_health(self):
"""Uses internal state to track trends"""
health = (self.budget - self.spent) / self.budget
self.health_history.append(health)
return healthproject.update_spent(5000)
The object maintains internal state—you only provide new
information.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Real-World Object Lifecycle:
Let’s follow a CampaignManager object through its complete
lifecycle:
Week 1 – Creation:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object Creation – Week 1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
q1_campaign = CampaignManager(“Q1 Product Launch”)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 2 – Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object Configuration – Week 2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
q1_campaign.add_channel(“email”, budget=5000)
q1_campaign.add_channel(“social”, budget=3000)
q1_campaign.create_asset(“launch_video”)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 3 – Execution:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object Execution – Week 3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
q1_campaign.launch()
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 4 – Monitoring:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object Monitoring – Week 4
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
q1_campaign.record_metrics({
’email’: {
‘sent’: 10000,
‘opened’: 2500,
‘clicked’: 500
},
‘social’: {
‘impressions’: 50000,
‘engagements’: 1500
}
})
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 5 – Analysis:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object Analysis – Week 5
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
report = q1_campaign.generate_performance_report()
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The object evolves through its lifecycle, remembering
everything.
Object Categories in Practice:
Content Objects:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Content Object – BlogTemplate
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class BlogTemplate:
def init(self, style_guide):
self.style_guide = style_guide
self.used_headlines = [] # Prevents repetition
self.performance_data = {}
def generate_post(self, topic):
#H->AI::Context: (Use style_guide, avoid
used_headlines)
headline = create_unique_headline(topic)
self.used_headlines.append(headline)
return blog_post━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Workflow Objects:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Workflow Object – HiringWorkflow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class HiringWorkflow:
def init(self, role):
self.role = role
self.stage = “defining requirements”
self.candidates = []
self.interviews_scheduled = {}
def advance_candidate(self, candidate_id, decision):
"""Object tracks each candidate through complete
process"""
if decision == "proceed":
self.schedule_next_round(candidate_id)
elif decision == "decline":
self.send_rejection(candidate_id)
self.update_pipeline_metrics()━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Validation Objects:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Validation Object – ContentValidator
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class ContentValidator:
def init(self, brand_rules):
self.brand_rules = brand_rules
self.violations_found = []
self.common_issues = {}
def check_content(self, content):
#H->AI::Directive: (Validate against
self.brand_rules)
# Maintains history of common violations for
# trend analysis
return validation_report━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How Objects Remember:
Objects maintain state between interactions through their
attributes:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Object Memory Across Multiple Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
project = ProjectTracker(“Website Redesign”,
budget=50000)
project.add_milestone(“Design Complete”, “2024-02-01”)
project.complete_milestone(“Design Complete”)
project.update_spent(15000)
print(project.status) # “active”
print(project.spent) # 15000
health_report = project.generate_report()
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
No re-explanation needed. The object maintains complete
context.
Example:
Complete Object – Sales Opportunity Tracker:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Complete Object – SalesOpportunity
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class SalesOpportunity:
def init(self, lead_data):
self.lead = lead_data
self.score = self.calculate_lead_score()
self.stage = “qualification”
self.activities = []
self.next_action = None
self.forecast_close_date = None
def log_activity(self, activity_type, notes):
"""Records all interactions with prospect"""
self.activities.append({
'date': today(),
'type': activity_type,
'notes': notes
})
self.update_stage_if_needed()
def advance_stage(self):
"""Moves opportunity through sales stages"""
stage_sequence = [
"qualification",
"discovery",
"proposal",
"negotiation",
"closed"
]
current_index = stage_sequence.index(self.stage)
if current_index < len(stage_sequence) - 1:
self.stage = stage_sequence[current_index + 1]
self.suggest_next_action()
def generate_opportunity_summary(self):
#H->AI::Directive: (Create executive summary of
this.lead)
#H->AI::Context: (Current stage: {self.stage},
score: {self.score})
#H->AI::Context: (Recent activities:
{self.activities[-3:]})
#H->AI::Focus: (Recommend actions to advance
opportunity)
return summaryopp = SalesOpportunity(acme_lead)
opp.log_activity(“discovery_call”,
“Identified pain points: manual reporting”)
opp.advance_stage() # Moves to discovery
opp.log_activity(“demo”,
“Showed reporting automation features”)
summary = opp.generate_opportunity_summary()
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* Objects maintain identity and state across sessions—
transforming AI from stateless to stateful
* Unlike functions that need all inputs each time,
objects remember their internal state
* Objects combine data (attributes) with behavior
(methods) into intelligent entities
* Track history and build trends automatically—every
interaction adds to the object’s memory
* Categories include content objects, workflow objects,
validation objects, and business entities
* Object lifecycle spans weeks or months—they evolve as
your project progresses
* Perfect for project tracking, campaign management,
customer relationships, budget monitoring
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How do I set up CRAFT in my environment?
Quick Answer:
CRAFT requires no installation or special setup—just open your
preferred AI chat platform (Claude, ChatGPT, or Gemini), create
a text file for your project, and start using CRAFT syntax. For
serious projects, use the standardized 4-file system in any text
editor.
Detailed Explanation:
CRAFT’s beauty lies in its simplicity: it’s a communication
methodology, not software. There’s no installation, no
dependencies, and no technical environment to configure.
Minimal Setup (Beginner Level):
Step 1: Choose Your AI Platform
Open any AI chat interface you already use:
* Claude (Anthropic)
* ChatGPT (OpenAI)
* Gemini (Google)
* Other large language models
Step 2: Start Using CRAFT Syntax
Simply type CRAFT-formatted instructions directly into your
chat:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Your First CRAFT Commands
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme Corp”
#H->AI::Directive: (Write a product announcement)
#H->AI::Context: (Use COMPANY_NAME)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
That’s it. You’re using CRAFT.
Recommended Setup (Serious Projects):
Step 1: Choose a Text Editor
Pick any plain text editor (not Microsoft Word):
* Windows: Notepad, Notepad++, VS Code
* Mac: TextEdit (plain text mode), VS Code, Sublime
Text
* Cross-platform: Google Docs, VS Code, Atom
Step 2: Create Your First CRAFT File
Create a single text file to store your project variables:
my_project.txtInside, define your project basics:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Basic CRAFT Project File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROJECT_NAME = “Marketing Campaign Q1”
COMPANY = “Acme Corp”
TARGET_AUDIENCE = “Small business owners”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3: Use It In Your AI Sessions
* Open your AI chat
* Copy and paste your CRAFT file content
* Add your directive:━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Using Your CRAFT File in AI Chat
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create social media posts for our
campaign)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Professional Setup (4-File System):
For ongoing projects requiring state management and session
continuity, use CRAFT’s standardized 4-file structure:
File 1: Project Implementation
* Filename: CFT-PROJ-025_MY-PROJECT-v1a.txt
* Contains: Your variables, functions, objects
File 2: Chat History
* Filename: CFT-PROJ-025_AI-CHAT-HISTORY-v1a.txt
* Contains: Session handoffs and continuity data
File 3: Framework Specification
* Filename: CFT-FWK-SPEC-v0925g9.txt
* Download from: CRAFTFramework.ai
* Contains: CRAFT rules and standards (read-only)
File 4: Framework Cookbook
* Filename: CFT-FWK-COOKBK-CORE-v1025d1.txt
* Download from: CRAFTFramework.ai
* Contains: Pre-built recipes and patterns (read-only)
Workspace Organization:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Professional CRAFT File Organization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/My_CRAFT_Projects/
/Project_025_Marketing/
CFT-PROJ-025_MY-PROJECT-v1a.txt
CFT-PROJ-025_AI-CHAT-HISTORY-v1a.txt
CFT-FWK-SPEC-v0925g9.txt
CFT-FWK-COOKBK-CORE-v1025d1.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What You DON’T Need:
* ❌ Programming environment or IDE
* ❌ Version control system (though Git helps for
teams)
* ❌ Special AI API access
* ❌ Command-line knowledge
* ❌ Server or hosting setup
* ❌ Database or storage systemKey Points:
* CRAFT is a communication methodology, not software
requiring installation
* Begin with a single text file containing basic
variables
* Grow to the 4-file system as projects become more
complex
* Works with any modern AI chat platform without
modification
* Text files are portable, shareable, and work across
all operating systems
* Professional setup requires only a text editor and
file organization
Related Topics:
* What file format should I use for CRAFT projects?
* How do I organize my CRAFT project files?
* What do I need to start using CRAFT?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What file format should I use for CRAFT projects?
Quick Answer:
Use plain text files (.txt) with Python-compatible syntax.
CRAFT files must be saved as .txt (not .docx or .rtf) and use
standardized naming: CFT-PROJ-[number]_[NAME]-v[version].txt
for projects, with version tracking like v1a, v1b, v2a.
Detailed Explanation:
CRAFT uses plain text files because they’re universal,
lightweight, and compatible with all AI platforms. The framework
uses Python-compatible syntax, making files both human-readable
and AI-parseable.
Required File Format:
File Type: Plain text (.txt)
* ✅ Can be opened by any text editor
* ✅ Works across all operating systems
* ✅ AI platforms can read them directly
* ✅ No formatting corruption
Incompatible Formats:
* ❌ Microsoft Word (.docx, .doc)
* ❌ Rich Text Format (.rtf)
* ❌ PDF (.pdf)
* ❌ Any format with embedded styling
Standardized Naming Conventions:
CRAFT uses specific filename patterns for automatic recognition:
Project Implementation Files:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Project Implementation File Naming Pattern
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pattern:
CFT-PROJ-[project_number]_[PROJECT-NAME]-v[version].txt
Examples:
CFT-PROJ-025_MARKETING-CAMPAIGN-v1a.txt
CFT-PROJ-043_CRAFTFRAMEWORK-AI-LAUNCH-v1e.txt
CFT-PROJ-101_CLIENT-ONBOARDING-v2c.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Chat History Files:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Chat History File Naming Pattern
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pattern:
CFT-PROJ-[project_number]_AI-CHAT-HISTORY-v[version].txt
Examples:
CFT-PROJ-025_AI-CHAT-HISTORY-v1a.txt
CFT-PROJ-043_AI-CHAT-HISTORY-v1d.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Framework Files (provided by CRAFT):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Framework File Naming Pattern
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CFT-FWK-SPEC-v[version].txt
CFT-FWK-COOKBK-CORE-v[version].txt
Examples:
CFT-FWK-SPEC-v0925g9.txt
CFT-FWK-COOKBK-CORE-v1025d1.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version Numbering System:
CRAFT uses an alphabetic micro-versioning system:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Version Numbering System
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Format: v[major][minor][micro]
Examples:
v1a = Version 1, iteration A (first version)
v1b = Version 1, iteration B (small changes)
v1c = Version 1, iteration C (more small changes)
v2a = Version 2, iteration A (major revision)
When to increment:
Micro version (a→b→c):
Small changes, typo fixes, minor additions
Minor version (1→2):
Significant feature additions or restructuring
Major version (would be v10a, v20a):
Complete overhaul
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Syntax Requirements:
CRAFT files use Python-compatible syntax but are still just
plain text:
Valid Syntax:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Valid CRAFT Syntax
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROJECT_NAME = “My Project”
COMPANY = “Acme Corp”
TARGET_MARKETS = [“USA”, “Canada”, “UK”]
BRAND_COLORS = {
“primary”: “#0077B6“,
“secondary”: “#03045E“
}
#H->AI::Directive: (Create marketing plan)
#H->AI::Context: (Use PROJECT_NAME and COMPANY)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Encoding:
Recommended: UTF-8 encoding
* Supports all characters and symbols
* Universal compatibility
* Standard for modern text files
How to ensure UTF-8:
* Most modern text editors default to UTF-8
* VS Code: Check bottom-right corner, click to change
* Notepad++: Encoding menu → UTF-8
* TextEdit (Mac): Plain text mode automatically uses
UTF-8
Line Endings:
CRAFT is agnostic to line ending style:
* Windows: CRLF (rn) – works fine
* Mac/Linux: LF (n) – works fine
* Mixed: Not recommended but won’t break functionality
File Organization Best Practices:
Keep related files together:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: File Organization Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/CRAFT_Projects/
/Project_025/
CFT-PROJ-025_MARKETING-v1c.txt
CFT-PROJ-025_AI-CHAT-HISTORY-v1c.txt
CFT-FWK-SPEC-v0925g9.txt (shared)
CFT-FWK-COOKBK-CORE-v1025d1.txt (shared)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Share framework files across projects:
* Keep one copy of CFT-FWK-SPEC
* Keep one copy of CFT-FWK-COOKBK-CORE
* Update both when new versions released
* Copy into each project folder OR reference centrally
Key Points:
* Always use .txt files, never .docx or .rtf
* Follow standardized naming:
CFT-PROJ-[number]_[NAME]-v[version].txt
* Use alphabetic micro-versioning (v1a, v1b, v2a)
* Save with UTF-8 encoding for maximum compatibility
* Python-compatible syntax, but files remain plain text
* Framework files (spec and cookbook) are shared across
all projects
Related Topics:
* How do I set up CRAFT in my environment?
* How do I organize my CRAFT project files?
* Can I use version control with CRAFT files?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How do I integrate CRAFT with different AI platforms?
Quick Answer:
CRAFT works identically across Claude, ChatGPT, and Gemini—
simply copy your CRAFT files into any AI chat and use the same
syntax. Platform-specific features (like Claude’s Projects or
ChatGPT’s Custom Instructions) can enhance CRAFT but aren’t
required.
Detailed Explanation:
CRAFT is platform-agnostic by design. The framework doesn’t
require API access or special integration—it’s a structured
communication methodology that works with any conversational AI.
Universal CRAFT Workflow (All Platforms):
Step 1: Start New Chat Session
* Open your AI platform of choice
Step 2: Load CRAFT Context
* Copy your project file content
* Paste into the chat
Step 3: Use CRAFT Directives
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: CRAFT Directive in Any Platform
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Execute CHAT-INIT recipe)
#H->AI::Context: (Session type: continue, Project: 025,
Handoff: H003)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4: Work Normally
* AI recognizes CRAFT syntax
* Responds using CRAFT comment system
* Maintains structure throughout session
This workflow is identical across all platforms.
Platform-Specific Optimizations:
Claude (Anthropic):
Platform Features That Enhance CRAFT:
* Projects: Store all 4 CRAFT files permanently in a
Claude Project
– Files persist across sessions automatically
– No manual copy/paste needed after initial setup
– Claude reads project files at session start
* Artifacts: Claude can create CRAFT-formatted
artifacts
- Generates downloadable .txt files
- Useful for exporting new versionsHow to Use:
1. Create a Claude Project for your CRAFT project
2. Upload all 4 files to the project
3. Claude auto-loads them in every chat
4. Update files in the project when versions change
ChatGPT (OpenAI):
Platform Features That Enhance CRAFT:
* Custom Instructions: Store frequently-used CRAFT
variables
– Limited to ~1,500 characters
– Best for: company name, brand voice, core
constants
* File Upload: Attach CRAFT files to individual
messages
- Upload .txt files directly in chat
- GPT reads and references them
- Must re-upload in each new chatHow to Use:
1. Put core variables in Custom Instructions:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: ChatGPT Custom Instructions Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY = “Acme Corp”
BRAND_VOICE = “Professional yet approachable”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2. Upload full CRAFT project files at chat start
3. Reference uploaded files in directivesGemini (Google):
Platform Features That Enhance CRAFT:
* Google Drive Integration: Store CRAFT files in Drive
– Reference files by sharing link
– Gemini can read public Drive files
* Extensions: Connect with Google Workspace
- Access Docs/Sheets alongside CRAFT
- Useful for CRAFT-driven document creationHow to Use:
1. Store CRAFT files in Google Drive
2. Set file permissions to “Anyone with link can view”
3. Share link in Gemini chat:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Gemini with Google Drive
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: (My CRAFT project: [Drive link])
#H->AI::Directive: (Load the file and proceed with
CHAT-INIT)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cross-Platform Compatibility:
What Works Everywhere:
* ✅ All CRAFT syntax (comments, variables, functions)
* ✅ 4-file system structure
* ✅ Recipe execution
* ✅ Handoff system
* ✅ Session continuity (via manual file updates)
Platform Limitations to Know:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Platform Comparison Table
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FeatureClaudeChatGPTGeminiFile✅❌⚠️persistenceProjectsRe-uploadDrive
| | | links—————-|———|———|———-
Token limit~180K~120K~32KMulti-file✅✅⚠️handlingExcellentGoodLimited--------------------------------------------Artifacts/✅⚠️⚠️DownloadsNativeVia CodeManual
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Switching Between Platforms:
CRAFT files are 100% portable:
Moving from Claude → ChatGPT:
1. Download files from Claude Project
2. Upload to ChatGPT at chat start
3. Continue working—no syntax changes needed
Moving from ChatGPT → Gemini:
1. Copy CRAFT files to Google Drive
2. Share Drive links in Gemini
3. AI reads files and continues
Best Practice for Multi-Platform:
* Keep master CRAFT files in local folder or cloud
storage
* Copy/upload to whichever platform you’re using
* Update master files after each session
* Version tracking works across platforms
API Integration (Advanced):
For users with API access, CRAFT can be embedded in system
messages:
Claude API:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Claude API Integration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import anthropic
client = anthropic.Client(api_key=”your_key”)
craft_context = open(
“CFT-PROJ-025_MY-PROJECT-v1a.txt”
).read()
response = client.messages.create(
model=”claude-sonnet-4-20250514″,
max_tokens=4096,
system=craft_context, # CRAFT as system context
messages=[
{
“role”: “user”,
“content”: “#H->AI::Directive: (Generate Q2
strategy)”
}
]
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OpenAI API:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: OpenAI API Integration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
import openai
craft_context = open(
“CFT-PROJ-025_MY-PROJECT-v1a.txt”
).read()
response = openai.ChatCompletion.create(
model=”gpt-4″,
messages=[
{
“role”: “system”,
“content”: craft_context
},
{
“role”: “user”,
“content”: “#H->AI::Directive: (Generate Q2
strategy)”
}
]
)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* CRAFT works identically across all major AI platforms
* No API access or integration setup required
* Platform-specific features (Projects, Custom
Instructions) enhance convenience but aren’t
necessary
* Files are 100% portable between platforms
* Token limits vary—Claude supports largest CRAFT
projects
* API integration possible for advanced automation
Related Topics:
* What are the technical requirements and limitations?
* Can I use CRAFT with multiple AI assistants?
* How do I set up CRAFT in my environment?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What are the technical requirements and limitations?
Quick Answer:
CRAFT has minimal technical requirements (just a text editor and
AI access) but is subject to AI platform limitations: token
limits (32K-180K depending on platform), file size constraints,
and lack of true code execution. CRAFT works within these
constraints through efficient structure and state management.
Detailed Explanation:
CRAFT is designed to work within the natural constraints of
conversational AI platforms. Understanding these limitations
helps you structure projects effectively.
Technical Requirements:
Minimal Requirements:
* ✅ Modern AI chat access (Claude, ChatGPT, or Gemini)
* ✅ Text editor (any plain text editor)
* ✅ Basic text file management
* ✅ Ability to copy/paste text
Optional But Helpful:
* Code editor with syntax highlighting (VS Code,
Sublime)
* Version control system (Git for team projects)
* Cloud storage for file backup
No Requirements For:
* ❌ Programming knowledge
* ❌ Special software installation
* ❌ API access
* ❌ Database or server
* ❌ Internet connection beyond AI chat access
Platform Token Limitations:
Token limits determine how much context an AI can process:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Platform Token Limits Comparison
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude Sonnet 4.5 ~180,000 tokens ✅ Handles large
projects easily
Claude Opus 4 ~180,000 tokens ✅ Best for complex
frameworks
ChatGPT-4 ~120,000 tokens ✅ Good for most
projects
Gemini 1.5 Pro ~32,000 tokens ⚠️ Smaller projects
only
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Token Estimation:
* 1 token ≈ 0.75 words
* Average CRAFT project file: 5,000-15,000 tokens
* Framework Spec + Cookbook: ~40,000 tokens
* Total 4-file system: 50,000-60,000 tokens
Managing Token Limits:
1. Use TOKEN-MONITOR recipe to track usage
2. Break large projects into sub-projects
3. Archive old handoffs after 5-10 sessions
4. Choose Claude for token-intensive projects
File Size Constraints:
Recommended File Sizes:
* Project Implementation: 20-50 KB (5,000-15,000
lines)
* Chat History: Grow over time, archive when >100 KB
* Framework files: Fixed size, provided by CRAFT
Platform Upload Limits:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Platform Upload Limits Comparison
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude Projects 10 MB per file 50 files
ChatGPT ~500 KB practical 10 per message
Gemini Via Drive, Varies
~10 MB
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Best Practices:
* Keep individual files under 500 KB
* Split mega-projects into multiple project files
* Use handoff archiving for long-running projects
Platform Capabilities:
What AI Platforms CAN Do:
* ✅ Parse and understand CRAFT syntax
* ✅ Maintain context within session
* ✅ Generate CRAFT-formatted responses
* ✅ Execute CRAFT recipes
* ✅ Track state via handoff system
What AI Platforms CANNOT Do:
* ❌ Persist memory between sessions (without file
reloading)
* ❌ Execute actual code (Python/JavaScript)
* ❌ Access external systems directly
* ❌ Modify your local files
* ❌ Store data permanently (without Projects feature)
CRAFT Workarounds:
* No persistence → Handoff system + file reloading
* No code execution → Generate code AI, user runs it
* No external access → User provides data, AI
structures it
* No file modification → AI generates updated
versions, user saves
Session Limitations:
Single Session Limits:
* Duration: Most platforms timeout after 1-2 hours
idle
* Messages: Unlimited, but token budget accumulates
* Complexity: Context degrades after 50+ message
exchanges
CRAFT Solutions:
* Use HANDOFF_SNAPSHOT recipe before long breaks
* Start fresh sessions for new major tasks
* Reference previous handoffs for continuity
Collaboration Constraints:
Current Limitations:
* No real-time collaborative editing
* No automatic sync across team members
* No built-in version control
CRAFT Workarounds:
* Manual file sharing (email, Dropbox, Git)
* Version numbering system (v1a, v1b, v2a)
* Handoff system documents all changes
* Git integration for technical teams
Data Privacy Considerations:
What to Know:
* AI platforms process all uploaded content
* Data may be used for training (platform-dependent)
* Sensitive information should be abstracted
Best Practices:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Abstracting Sensitive Data
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use placeholders for sensitive data:
CLIENT_NAME = “[REDACTED]”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
* Check platform privacy policies
* Enterprise accounts offer enhanced privacy
* Never include: passwords, API keys, PIIFuture-Proofing:
CRAFT’s Design for Adaptation:
* Platform-agnostic syntax works as AI evolves
* Text files remain readable regardless of platform
changes
* Recipe system allows updates without breaking old
projects
* Version tracking maintains backward compatibility
Key Points:
* Minimal technical requirements: text editor + AI
access
* Token limits vary (32K-180K) – choose platform based
on project size
* File sizes should stay under 500 KB for optimal
performance
* AI cannot execute code or persist data natively
* CRAFT’s handoff system compensates for lack of
persistence
* Platform privacy policies vary—abstract sensitive
data
* Framework designed to adapt as AI capabilities evolve
Related Topics:
* How do I integrate CRAFT with different AI
platforms?
* Can I use CRAFT with multiple AI assistants?
* What file format should I use for CRAFT projects?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How do I organize my CRAFT project files?
Quick Answer:
CRAFT uses a standardized 4-file system: (1) Project
Implementation file contains your variables/functions, (2) Chat
History file tracks session continuity, (3) Framework
Specification defines CRAFT rules, and (4) Cookbook provides
pre-built recipes. Keep all four files in your project folder
for easy access.
Detailed Explanation:
CRAFT’s file organization system is designed for clarity,
consistency, and ease of use across projects. The 4-file
structure ensures every project has complete context while
maintaining separation of concerns.
The 4-File System Explained:
File 1: Project Implementation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File 1: Project Implementation Naming
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Filename:
CFT-PROJ-[number]_[PROJECT-NAME]-v[version].txt
Example:
CFT-PROJ-025_MARKETING-CAMPAIGN-v1c.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Purpose: Your project’s “brain”
Contains:
* Project metadata (name, ID, version, owner)
* Project variables (company info, target audience,
etc.)
* Custom functions for your project
* Custom objects and data types
* Project-specific instructions for AI
You Modify: ✅ Frequently
Size: 20-100 KB typical
Shared: Within your team
File 2: Conversation Continuity (Chat History)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File 2: Chat History Naming
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Filename:
CFT-PROJ-[number]_AI-CHAT-HISTORY-v[version].txt
Example:
CFT-PROJ-025_AI-CHAT-HISTORY-v1c.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Purpose: Session-to-session memory
Contains:
* Handoff snapshots from each session
* Key decisions made
* Current project state
* Next steps
* Unresolved questions
You Modify: ✅ After each session (via HANDOFF recipe)
Size: Grows over time (5-50 KB per handoff)
Shared: Within your team
File 3: Framework Specification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File 3: Framework Specification Naming
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Filename:
CFT-FWK-SPEC-v[version].txt
Example:
CFT-FWK-SPEC-v0925g9.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Purpose: CRAFT “constitution”
Contains:
* CRAFT framework rules
* Comment system definitions
* Data type specifications
* Function standards
* Recipe system documentation
You Modify: ❌ Never (provided by CRAFT)
Size: ~100-200 KB
Shared: Used across ALL projects
File 4: Framework Cookbook
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File 4: Framework Cookbook Naming
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Filename:
CFT-FWK-COOKBK-CORE-v[version].txt
Example:
CFT-FWK-COOKBK-CORE-v1025d1.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Purpose: Pre-built recipe library
Contains:
* CHAT-INIT recipe
* HANDOFF_SNAPSHOT recipe
* TOKEN-MONITOR recipe
* 15+ other base recipes
You Modify: ❌ Never (provided by CRAFT)
Size: ~150-300 KB
Shared: Used across ALL projects
File Organization Patterns:
Option 1: Simple Single-Project Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Single Project Organization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/Documents/
/My_CRAFT_Project/
CFT-PROJ-025_MARKETING-v1c.txt
CFT-PROJ-025_AI-CHAT-HISTORY-v1c.txt
CFT-FWK-SPEC-v0925g9.txt
CFT-FWK-COOKBK-CORE-v1025d1.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Option 2: Multiple Projects (Recommended)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Multiple Projects Organization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/Documents/
/CRAFT_Projects/
/CRAFT_Framework_Files/
CFT-FWK-SPEC-v0925g9.txt ← Shared
CFT-FWK-COOKBK-CORE-v1025d1.txt ← Shared
/Project_025_Marketing/
CFT-PROJ-025_MARKETING-v1c.txt
CFT-PROJ-025_AI-CHAT-HISTORY-v1c.txt
/Project_043_Website_Launch/
CFT-PROJ-043_WEBSITE-LAUNCH-v1e.txt
CFT-PROJ-043_AI-CHAT-HISTORY-v1e.txt
/Project_087_Product_Dev/
CFT-PROJ-087_PRODUCT-DEV-v2a.txt
CFT-PROJ-087_AI-CHAT-HISTORY-v2a.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Option 3: Team/Enterprise Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Team/Enterprise Organization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/Shared_Drive/
/Company_CRAFT/
/Framework/ (shared, read-only)
CFT-FWK-SPEC-v0925g9.txt
CFT-FWK-COOKBK-CORE-v1025d1.txt
/Active_Projects/
/025_Marketing_Q1/
/043_Website_Redesign/
/087_Product_Launch/
/Archived_Projects/
/Completed/
/On_Hold/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version Control Integration:
For Git Users:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Git Repository Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
my-craft-project/
├── .gitignore
├── README.md
├── CFT-PROJ-025_MARKETING-v1c.txt
├── CFT-PROJ-025_AI-CHAT-HISTORY-v1c.txt
├── framework/
│ ├── CFT-FWK-SPEC-v0925g9.txt
│ └── CFT-FWK-COOKBK-CORE-v1025d1.txt
└── archive/
├── CFT-PROJ-025_MARKETING-v1a.txt
└── CFT-PROJ-025_MARKETING-v1b.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
.gitignore example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: .gitignore File Contents
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
*-v1a.txt
*-v1b.txt
!*-v1c.txt
*.tmp
*~
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Lifecycle Management:
Active Files:
* Keep current version in main project folder
* Update version number with changes (v1a → v1b)
Archiving Old Versions:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Archiving Old Versions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/Project_025/
CFT-PROJ-025_MARKETING-v1e.txt ← Current
CFT-PROJ-025_AI-CHAT-HISTORY-v1e.txt ← Current
/Archive/
CFT-PROJ-025_MARKETING-v1a.txt
CFT-PROJ-025_MARKETING-v1b.txt
CFT-PROJ-025_MARKETING-v1c.txt
CFT-PROJ-025_MARKETING-v1d.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Handoff History Pruning:
When Chat History file exceeds 100 KB:
1. Create archive file:
CFT-PROJ-025_AI-CHAT-HISTORY-ARCHIVE-H001-H050.txt
2. Move old handoffs (H001-H050) to archive
3. Keep recent handoffs (H051-current) in main file
4. Reference archive when needed
Framework File Updates:
When CRAFT releases new framework versions:
Step 1: Download New Versions
* Download updated CFT-FWK-SPEC-v[new].txt
* Download updated CFT-FWK-COOKBK-CORE-v[new].txt
Step 2: Replace in Shared Location
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Updating Framework Files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
/CRAFT_Framework_Files/
CFT-FWK-SPEC-v0925g9.txt ← Replace
CFT-FWK-COOKBK-CORE-v1025d1.txt ← Replace
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3: All Projects Automatically Updated
* No changes needed to individual project files
* Next session uses new framework versions
Cloud Storage Recommendations:
Best Practices:
* Google Drive: Create “CRAFT Projects” folder, share
with team
* Dropbox: Use selective sync for large projects
* OneDrive: Business accounts best for team sharing
* iCloud: Good for individual Mac users
Sync Strategy:
* Sync project files actively being worked on
* Archive completed projects locally to save space
* Keep framework files synced always
Backup Strategy:
3-2-1 Backup Rule:
* 3 copies of your CRAFT files
* 2 different storage types (local + cloud)
* 1 offsite backup
Example:
1. Working copy on computer
2. Cloud backup (Google Drive)
3. External hard drive monthly backup
Key Points:
* Use standardized 4-file system for all projects
* Project files are project-specific, modified
frequently
* Framework files are universal, never modified by
users
* Organize multiple projects in separate folders
* Share framework files across all projects
* Archive old versions to manage file size
* Prune handoff history when files exceed 100 KB
* Version control (Git) works great with CRAFT text
files
* Cloud storage enables team collaboration
Can I use CRAFT with multiple AI assistants?
Quick Answer:
Yes—CRAFT files work identically across Claude, ChatGPT, and
Gemini. You can start a project in one AI, continue it in
another, or use different AIs for different tasks within the
same project. Simply copy your CRAFT files to whichever platform
you’re using.
Detailed Explanation:
CRAFT’s platform-agnostic design means your projects are truly
portable. The same files, the same syntax, the same results—
regardless of which AI you’re using.
Cross-Platform Workflow:
Scenario 1: Starting in Claude, Continuing in ChatGPT
Session 1 (Claude):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Session 1 in Claude
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 2 (ChatGPT):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Session 2 in ChatGPT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 3 (Back to Claude):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Session 3 Back in Claude
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why Multi-Platform Works:
Platform-Independent Elements:
* ✅ CRAFT syntax (comments, variables, functions)
* ✅ File structure (4-file system)
* ✅ Naming conventions
* ✅ Version tracking
* ✅ Handoff system
* ✅ Recipe execution
Platform-Specific Features Don’t Transfer:
* ❌ Claude Projects (file persistence)
* ❌ ChatGPT Custom Instructions
* ❌ Gemini Drive integration
* ❌ Platform-specific artifacts
Solution: Core CRAFT in files, not platform features
Choosing the Right AI for Each Task:
Claude (Best For):
* Complex reasoning and analysis
* Long-form content creation
* Large CRAFT projects (180K token context)
* Multi-file project management
* Detailed code generation
ChatGPT (Best For):
* Quick iterations and brainstorming
* Creative content variations
* Plugin/tool integrations
* Real-time web search (with plugins)
* Casual conversational tasks
Gemini (Best For):
* Google Workspace integration
* Multi-modal tasks (if using images)
* Quick lookups and summaries
* Tasks requiring Google services
Multi-AI Strategy Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Multi-AI Project Strategy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Project 025: Marketing Campaign
Claude → Strategic planning, content frameworks
ChatGPT → Social media variations, quick edits
Gemini → Google Docs integration, calendar planning
All using same CRAFT project files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Practical Multi-Platform Scenarios:
Scenario 1: Token Limit Management
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Managing Token Limits Across Platforms
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Problem: Project approaching ChatGPT’s 120K token limit
Solution: Switch to Claude (180K limit) for remainder
Steps:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scenario 2: Platform Feature Utilization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Using Different Platforms Throughout the Day
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Morning: Claude for deep strategy work
– Upload files to Claude Project
– Develop complex frameworks
– Create handoff H005
Afternoon: ChatGPT for rapid iterations
– Upload files + H005 to ChatGPT
– Generate 20 headline variations
– Quick edits and tweaks
– Create handoff H006
Evening: Gemini for Google Docs transfer
– Upload files + H006 to Gemini
– Transfer content to Google Docs
– Share with team
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scenario 3: Team Collaboration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Team Members Using Different Platforms
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Team Member A (prefers Claude):
– Works on data analysis portions
– Creates handoff H007
Team Member B (prefers ChatGPT):
– Loads files with H007
– Works on content writing
– Creates handoff H008
Both using same project files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Synchronization Strategy:
Recommended Workflow:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: File Sync Workflow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Avoid:
* Working on different versions simultaneously
* Forgetting to upload latest handoff
* Mixing version numbers across platforms
Handling Platform Differences:
Token Context Awareness:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Tracking Platform Usage in Project File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SESSION_HISTORY = {
“H001”: “Claude – Strategic planning”,
“H002”: “Claude – Framework development”,
“H003”: “ChatGPT – Content variations”,
“H004”: “Claude – Final review”
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Platform-Specific Notes in Handoffs:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Platform Notes in Handoff
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PLATFORM_NOTES = “Using Claude for this session due to
complex reasoning requirements. May switch to
ChatGPT for next session’s iteration tasks.”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cost Considerations:
Platform Pricing (as of 2025):
* Claude: Subscription or API usage
* ChatGPT: Free tier + Plus subscription + API
* Gemini: Free tier + Advanced + API
Multi-Platform Strategy:
* Use free tiers for simple tasks
* Reserve premium for complex CRAFT projects
* API access for automation (advanced)
Cost Optimization:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Cost Optimization Strategy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Simple updates → Free tier AI
Complex strategy → Premium Claude
Bulk variations → ChatGPT Plus
Quick lookups → Free Gemini
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Quality Consistency Across Platforms:
Maintaining Output Quality:
1. Use specific CRAFT directives (not
platform-dependent)
2. Leverage handoff system (documents all decisions)
3. Include examples in project files (shows expected
quality)
4. Use confidence calibration (#H->AI::EvaluateBy:
comments)
Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Ensuring Quality Across Platforms
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Generate social media posts)
#H->AI::Context: (Use BRAND_VOICE from project file)
#H->AI::EvaluateBy: (Tone matches examples in H002,
H003)
#H->AI::Constraint: (Must include CALL_TO_ACTION)
Result: Consistent quality regardless of AI platform
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
API Integration for Automation:
Advanced: Programmatic Multi-AI Usage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: API Integration Pseudo-Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def craft_task(task_type, craft_files):
if task_type == “strategic_analysis”:
return claude_api.execute(craft_files)
elif task_type == “content_variations”:
return chatgpt_api.execute(craft_files)
elif task_type == “google_docs_integration”:
return gemini_api.execute(craft_files)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* CRAFT files are 100% portable across Claude,
ChatGPT, and Gemini
* Handoff system enables seamless cross-platform
continuity
* Choose AI platform based on task requirements, not
CRAFT compatibility
* Same syntax, same files, consistent results across
platforms
* Platform-specific features don’t transfer, but core
CRAFT does
* Keep master files in shared location, sync
before/after sessions
* Multi-AI strategy can optimize for cost, features,
and capabilities
* Quality remains consistent through CRAFT structure,
not platform choice
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How do I know if I’m using CRAFT correctly?
Quick Answer:
You’re using CRAFT correctly if: (1) AI consistently follows
your instructions, (2) you rarely repeat context between
sessions, (3) responses are predictable and on-brand, and (4)
complex tasks become simpler over time through reusable
patterns. Success feels like AI “gets” your project.
Detailed Explanation:
CRAFT success isn’t measured by complexity—it’s measured by
outcomes. Here are the indicators that show you’re using CRAFT
effectively.
Success Indicator #1: Consistent AI Behavior
What Success Looks Like:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Consistent AI Output
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create social media post about new
feature)
#H->AI::Context: (Use BRAND_VOICE and TARGET_AUDIENCE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How to Test:
Run the same directive 3 times in different sessions. Results
should be remarkably similar in tone, quality, and adherence to
your variables.
Red Flag:
Wildly different results from identical directives = variables
not loading properly or directives too vague.
Success Indicator #2: Minimal Context Repetition
What Success Looks Like:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Define Once, Reference Forever
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme Corp”
TARGET_AUDIENCE = “IT managers”
BRAND_VOICE = “Technical but accessible”
[Just reference the variables, never explain them again]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Measure This:
* Count how many times you type the same information
* Good: Define once, reference forever
* Bad: Re-explaining company details every session
Before CRAFT:
“Our company is Acme Corp, we make CloudSync for IT managers at
mid-size companies, our tone is technical but accessible…”
[Every. Single. Time.]
With CRAFT:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Reference Variables Instead
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Use COMPANY_NAME, PRODUCT, and
TARGET_AUDIENCE)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If you’re still typing long explanations repeatedly, you’re not
leveraging CRAFT variables properly.
Success Indicator #3: Predictable Quality
What Success Looks Like:
You can predict the quality and style of AI output before seeing
it because your CRAFT structure is consistent.
The Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Predictable Output Quality
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create LinkedIn post announcing our
Q2 results)
#H->AI::Context: (Use BRAND_VOICE, mention
REVENUE_GROWTH)
#H->AI::Constraint: (150-200 characters, professional
tone)
Before You See Output, You Know:
✓ Tone will match brand voice
✓ Length will be in range
✓ Revenue growth will be mentioned
✓ Professional, not casual
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If Output is Surprising: Your directives might be too vague or
context insufficient.
Success Indicator #4: Decreasing Prompt Length
Natural CRAFT Evolution:
Week 1 (Learning):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Week 1 – Verbose Prompts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create a social media post about
our new product launch)
#H->AI::Context: (The product is CloudSync Pro, it’s
for IT managers)
#H->AI::Context: (Use professional but approachable
tone)
#H->AI::Constraint: (Keep under 200 characters)
#H->AI::Structure: (One sentence, one hashtag)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Month 3 (Mastery):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Month 3 – Concise Prompts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create product launch post for
LinkedIn)
Everything else is in variables, AI knows the pattern.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Trend: If prompts are getting SHORTER over time, you’re
building reusable structure correctly.
Success Indicator #5: Functions Emerge Naturally
What Success Looks Like:
You find yourself thinking: “I’ve done this exact task 5 times
now. I should make it a function.”
Example Evolution:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Natural Function Evolution
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def create_feature_announcement(feature_name,
key_benefit):
#H->AI::Directive: (Create announcement for
{feature_name})
#H->AI::Context: (Emphasize {key_benefit})
#H->AI::Context: (Use BRAND_VOICE, TARGET_AUDIENCE)
#H->AI::Structure: (Email format: subject + 3
paragraphs)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If You Never Create Functions: Either your work is too varied
(which is fine) OR you’re missing opportunities for
reusability.
Success Indicator #6: Handoffs Are Valuable
What Success Looks Like:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Effective Handoffs
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Continue from handoff H004)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Test:
Can you skip a week, come back, read your last handoff, and
immediately know where you left off?
If Yes: Your handoffs are working.
If No: Your handoffs are too vague or missing critical context.
Success Indicator #7: AI Provides Better Feedback
What Success Looks Like:
AI starts using CRAFT comment system BACK to you:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: AI Using CRAFT Comments
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#AI->H::Note: (This is the 4th time you’ve requested
this analysis)
#AI->H::Suggestion: (Consider creating a
generate_competitor_report() function)
#AI->H::Question: (Should I always use the same
metrics, or does it vary?)
#AI->H::Caution: (The BUDGET variable hasn’t been
updated since January)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This Means: AI understands your CRAFT structure well enough to
optimize it for you.
Success Indicator #8: New Team Members Onboard Quickly
The Test:
Give someone your CRAFT files. How long until they’re
productive?
Good CRAFT:
* Read project file → Understand immediately
* See variables → Know company context
* Review functions → Understand common patterns
* Check handoffs → Know project state
* Time to productivity: < 30 minutes
Poor CRAFT:
* Files are confusing
* Variables poorly named
* No clear patterns
* Handoffs missing
* Time to productivity: Multiple hours or days
Success Indicator #9: You’re Spending Time on Work, Not
Prompting
Measure This:
Before CRAFT:
* 60% time: Crafting the perfect prompt
* 30% time: Fixing AI misunderstandings
* 10% time: Actual productive work
With Good CRAFT:
* 10% time: Brief directive
* 10% time: Minor refinements
* 80% time: Actual productive work
If Prompting Still Takes Forever: Your CRAFT structure needs
simplification or your directives need clarity.
Success Indicator #10: Problems Become Patterns
What Success Looks Like:
First Time (Problem):
“I need to analyze competitor pricing. How should I approach
this?”
[20-minute back-and-forth]
Second Time (Pattern Recognition):
“This is similar to last time. Let me create a function.”
Third+ Times (Solution):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Problem Becomes Pattern
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
analyze_competitor(“Company X”, “enterprise pricing”)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Evolution: Problem → Pattern → Function → Efficiency
Self-Assessment Checklist
Rate yourself on these statements (1-5 scale):
CRAFT Basics:
☐ I load files at the start of every session
(5 = always, 1 = rarely)
☐ AI recognizes my variables consistently
(5 = always, 1 = rarely)
☐ My comment syntax is correct
(5 = always, 1 = often wrong)
☐ I create handoffs between sessions
(5 = always, 1 = never)
CRAFT Effectiveness:
☐ AI outputs match my expectations
(5 = always, 1 = rarely)
☐ I rarely repeat the same context
(5 = almost never repeat, 1 = repeat constantly)
☐ My prompts are getting shorter over time
(5 = much shorter, 1 = same length)
☐ I reuse functions/patterns regularly
(5 = frequently, 1 = never)
CRAFT Mastery:
☐ I can predict AI output quality
(5 = always, 1 = never)
☐ New team members understand my files quickly
(5 = under 30 min, 1 = takes hours)
☐ AI suggests optimizations to my structure
(5 = frequently, 1 = never)
☐ I spend more time on work than prompting
(5 = 80%+ on work, 1 = 20% on work)
Scoring:
* 48-60: CRAFT Master – Excellent usage
* 36-47: CRAFT Proficient – Solid understanding
* 24-35: CRAFT Learner – Keep practicing
* 12-23: CRAFT Beginner – Review fundamentals
* 0-11: Revisit core concepts
The Ultimate Test
Can you answer these 3 questions?
Key Points:
* Success = consistent AI behavior, not complex
structure
* Decreasing prompt length over time indicates good
CRAFT adoption
* Handoffs should provide immediate context in new
sessions
* Variables eliminate repetitive context-setting
* AI providing feedback via CRAFT comments = advanced
understanding
* Natural function creation from repeated patterns =
mastery
* Team onboarding time is a key quality indicator
* More time on work, less on prompting = CRAFT working
correctly
What are the most common CRAFT mistakes and how do I fix them?
Quick Answer:
The five most common mistakes are: (1) incorrect comment syntax,
(2) not reloading files between sessions, (3) overly complex
initial implementations, (4) mixing directives with context in
one comment, and (5) inconsistent naming conventions. Each has a
straightforward fix.
Detailed Explanation:
Learning from others’ mistakes accelerates your CRAFT mastery.
Here are the most common pitfalls and their solutions.
Mistake #1: Comment Syntax Errors
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Common Comment Syntax Errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive (Create report)
#H->AI::Directive: Create report
#AI->H::Directive: (Create report)
#H->AI::Directve: (Create report)
#H -> AI :: Directive: (Create report)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Perfect Comment Syntax
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create report)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Pattern: #H->AI::Type: (content)
* Hash mark starts it
* H->AI (human to AI) or AI->H (AI to human)
* Double colon before type
* Colon after type
* Content in parentheses
* No extra spaces
Prevention Tip: Copy a working comment as a template, then
change only the type and content.
Mistake #2: Not Reloading Files Between Sessions
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Wrong Mental Model
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
User Mental Model:
Session 1: Define variables → Work with AI
Session 2: Expect variables to still exist
Result: Variables undefined, AI confused
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why This Happens:
Users think “I uploaded files once, they should persist.” But
AI platforms are stateless.
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Proper Session Initialization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Execute CHAT-INIT recipe)
#H->AI::Context: (Project 025, continue from H003)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Or manually:
1. Re-attach/upload all 4 CRAFT files
2. AI loads context
3. Variables now available
Prevention Tip: Make file loading the first thing you do in
every session. No exceptions.
Mistake #3: Starting Too Complex
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Overly Complex Day 1 Implementation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class CampaignManager:
def init(self, segments, budget, timeline):
self.segment_analyzer = SegmentAnalyzer(
segments)
self.budget_allocator = BudgetOptimizer(budget)
self.timeline_tracker = TimelineManager(
timeline)
def generate_campaign(self):
# 50 more lines...CAMPAIGN_TYPES = DataType(“campaign”,
required_fields=[…])
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why This Fails:
* Overwhelming to maintain
* Hard to debug
* Often unnecessary for actual needs
* Discourages continued use
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Start Simple, Scale Gradually
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme Corp”
PRODUCT = “CloudSync Pro”
#H->AI::Directive: (Create social media post about our
product)
#H->AI::Context: (Use COMPANY_NAME and PRODUCT)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scale gradually:
* Week 1: Variables only
* Week 2: Add comment structure
* Month 1: First function (if needed)
* Month 3: Data types (if needed)
* Month 6+: Objects (if needed)
Prevention Tip: Add complexity only when pain points emerge.
CRAFT succeeds through incremental adoption.
Mistake #4: Mixing Intent in Comments
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Mixing Multiple Intents in One Comment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: (Create a marketing report analyzing
Q2 performance for the board meeting next week
focusing on ROI)
This mixes: directive, focus, context, and constraint
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Separate Comments for Each Intent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create Q2 marketing performance
report)
#H->AI::Context: (For board meeting next week)
#H->AI::Focus: (Emphasize ROI metrics)
#H->AI::Constraint: (Keep under 5 pages)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why Separation Matters:
* AI parses each comment type differently
* Mixing reduces clarity
* Harder for AI to prioritize information
* Makes prompts unscannable
Prevention Tip: One purpose per comment. If you’re writing a
long comment, split it.
Mistake #5: Inconsistent Naming Conventions
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Inconsistent Naming – Don’t Do This
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
company_name = “Acme”
PRODUCT_name = “CloudSync”
targetAudience = “IT Managers”
brand-voice = “Professional”
Four different naming styles in four lines
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Consistent Naming Conventions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme”
PRODUCT_NAME = “CloudSync”
TARGET_AUDIENCE = “IT Managers”
BRAND_VOICE = “Professional”
current_budget = 50000
users_active = 1250
Campaign = DataType(“campaign”, …)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why Consistency Matters:
* Makes code scannable
* Prevents typos
* Shows intent (constant vs variable)
* Follows Python conventions
Prevention Tip: Choose a convention (CRAFT recommends
Python-style) and stick to it project-wide.
Mistake #6: Forgetting Handoffs
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Forgetting to Create Handoffs
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session ends → Start new session → Lost all context
about what was accomplished
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why This Happens:
Users focus on getting work done, forget to document for next
session.
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Always Create Handoffs Before Ending
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Execute HANDOFF_SNAPSHOT recipe)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prevention Tip: Make handoffs habitual. Set a reminder: “End
session? Create handoff first.”
Mistake #7: Not Using Recipes
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Recreating Patterns Manually
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
User recreates common patterns manually each time
instead of using pre-built recipes
Example:
“I need you to initialize the session, load my context,
check my handoffs, and prepare for work…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Use Pre-Built Recipes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Execute CHAT-INIT recipe)
#H->AI::Context: (Project 025, continue, handoff H003)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Available Recipes:
* CHAT-INIT: Session initialization
* HANDOFF_SNAPSHOT: Session continuity
* TOKEN-MONITOR: Track context usage
* CONFIDENCE-CALIB: Probability estimates
* And 15+ more in the cookbook
Prevention Tip: Review the cookbook. If you’re doing something
repeatedly, there’s probably a recipe for it.
Mistake #8: Overusing Functions Too Early
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Creating Functions Too Early
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
def generate_content(type, audience, tone, length,
format, platform, cta):
# Complex logic here
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why This Is Wrong:
* Functions are for repeated multi-step processes
* Creating functions before establishing pattern =
premature optimization
* Harder to modify than simple directives
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Use Directives First, Functions Later
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Generate LinkedIn post)
#H->AI::Context: (Professional tone, for IT managers)
def create_linkedin_post(topic):
#H->AI::Directive: (Generate LinkedIn post about
{topic})
#H->AI::Context: (Professional tone, for IT
managers)
#H->AI::Constraint: (150-200 characters)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rule: Don’t create a function until you’ve manually repeated
the process 3-5 times.
Mistake #9: Ignoring AI Feedback
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Ignoring AI Warnings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI: #AI->H::Caution: (This variable name conflicts
with Python built-in)
User: [Ignores warning, continues]
Result: Unexpected behavior later
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Fix:
Pay attention to AI responses using CRAFT comment system:
* #AI->H::Caution: – Warnings you should address
* #AI->H::Question: – AI needs clarification
* #AI->H::Suggestion: – Optimization opportunities
Prevention Tip: When AI uses CRAFT comments back to you, read
them carefully. They contain important information.
Mistake #10: Not Versioning Files
The Error:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Poor File Versioning
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Saved files:
CRAFT-project.txt
CRAFT-project-new.txt
CRAFT-project-final.txt
CRAFT-project-final-FINAL.txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Proper CRAFT Version Naming
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Use CRAFT version naming:
CFT-PROJ-025_MARKETING-v1a.txt
CFT-PROJ-025_MARKETING-v1b.txt
CFT-PROJ-025_MARKETING-v2a.txt
Version Logic:
* v1a → v1b → v1c: Small changes
* v1c → v2a: Major revision
* Always know which version is current
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prevention Tip: Use CRAFT naming conventions from day one. They
exist for a reason.
Quick Reference: Top 10 Mistakes
❌ Wrong comment syntax
✅ Use exact format: #H->AI::Type: (content)
❌ Not reloading files
✅ Load files every session start
❌ Starting too complex
✅ Begin with variables only
❌ Mixing comment intents
✅ One purpose per comment
❌ Inconsistent naming
✅ Stick to one convention
❌ Skipping handoffs
✅ Create handoff before session ends
❌ Ignoring recipes
✅ Use pre-built recipes from cookbook
❌ Premature functions
✅ Wait until pattern repeated 3-5 times
❌ Ignoring AI feedback
✅ Read and act on AI's CRAFT comments
❌ Poor versioning
✅ Use CRAFT naming: CFT-PROJ-XXX-vYYY.txtKey Points:
* Most CRAFT mistakes are syntax or workflow issues,
not conceptual problems
* Comment syntax must be exact – AI parses it literally
* File reloading is non-negotiable for variable
persistence
* Start simple, add complexity only when pain points
emerge
* Consistent naming conventions prevent confusion
* Handoffs are critical for multi-session projects
* Use pre-built recipes instead of recreating patterns
* Pay attention when AI uses CRAFT comments back to you
The AI isn’t following my CRAFT instructions – what’s wrong?
Quick Answer:
Usually the issue is syntax errors in comment formatting,
unclear directives, or the AI not recognizing CRAFT files were
attached. Check your comment syntax (proper colons and
parentheses), make directives specific, and verify files are
actually attached to the chat.
Detailed Explanation:
When AI doesn’t follow CRAFT instructions, the problem typically
falls into one of five categories. Here’s how to diagnose and
fix each:
Issue 1: Comment Syntax Errors
Common Mistakes:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Common CRAFT Comment Syntax Errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive (Create a report)
#H->AI::Directive: Create a report
#AI->H::Directive: (Create a report)
#H->AI::Directive: (Create a report)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The Pattern:
* Human to AI: #H->AI::Type: (content)
* AI to Human: #AI->H::Type: (content)
* Always include the colon after the type
* Always wrap content in parentheses
Quick Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Testing Comment Syntax
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (Can you see this formatted comment?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If AI responds acknowledging the CRAFT comment structure, your
syntax is correct.
Issue 2: Vague or Ambiguous Directives
Problem Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Vague Directive – Don’t Do This
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Do the marketing thing)
Too vague – AI doesn’t know which “marketing thing”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Better Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Specific Directive – Do This Instead
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Generate 5 LinkedIn posts promoting
our Q2 product launch)
#H->AI::Context: (Use BRAND_VOICE and TARGET_AUDIENCE
from project variables)
#H->AI::Structure: (Each post should be 150-200
characters with one hashtag)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rule of Thumb:
* Directives should be specific actions
* Include relevant context
* Define expected output format
* Reference project variables when applicable
Issue 3: Files Not Actually Loaded
Symptoms:
* AI doesn’t recognize your variables
* AI asks for information that’s in your project file
* No acknowledgment of CRAFT structure
Diagnosis:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Testing File Loading
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (What is the value of PROJECT_NAME?)
If AI says it doesn’t see PROJECT_NAME (and it’s defined
in your file), the file wasn’t loaded properly.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Solutions:
* For Claude Projects: Verify files are uploaded to
the project, not just attached to one message
* For ChatGPT: Re-upload files at the start of each
new chat
* For Gemini: Verify Google Drive links are set to
“Anyone with link can view”
Issue 4: Conflicting Instructions
Problem Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Conflicting Instructions – Don’t Do This
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Write a detailed technical analysis)
#H->AI::Constraint: (Keep response under 100 words)
Contradiction: “detailed” vs “under 100 words”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Clear, Non-Conflicting Instructions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Write a technical analysis summary)
#H->AI::Constraint: (Keep response under 100 words)
#H->AI::Focus: (Prioritize key findings over
comprehensive details)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Check for:
* Contradictory constraints
* Conflicting context information
* Impossible combinations of requirements
Issue 5: Wrong Comment Type Used
Problem:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Wrong Comment Type – Don’t Do This
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: (Create a quarterly report)
Context is background info, not a command
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Correct Comment Type Usage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create quarterly report)
#H->AI::Context: (This is for board presentation next
week)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Comment Type Reference:
* Directive: Commands/actions (“Create”, “Analyze”,
“Generate”)
* Context: Background information (audience, purpose,
situation)
* Constraint: Hard boundaries (word limits, exclusions,
requirements)
* Question: Direct inquiries to AI
* Focus: Areas requiring emphasis
* Structure: Output format requirements
Diagnostic Workflow
When AI isn’t following instructions, try this sequence:
Step 1: Verify File Loading
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Step 1 – Verify Files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (Can you list the CRAFT files you
currently have access to?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2: Test Basic Syntax
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Step 2 – Test Syntax
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Respond with ‘CRAFT syntax
recognized’ if you see this formatted comment)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3: Check Variable Recognition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Step 3 – Check Variables
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (What is the value of COMPANY_NAME?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4: Simplify and Rebuild
Start with the simplest possible directive:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Step 4 – Start Simple
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (List the five core components of
CRAFT)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If this works, gradually add complexity until you find the
breaking point.
Quick Fixes Checklist
☐ Check comment syntax: #H->AI::Type: (content)
☐ Verify files are attached/uploaded
☐ Make directives specific and actionable
☐ Ensure no contradictory instructions
☐ Use correct comment types for intent
☐ Test with simple directive first
☐ Add context and constraints incrementallyKey Points:
* 90% of “AI not following CRAFT” issues are syntax
errors or missing files
* Comment format is strict: #H->AI::Type: (content) –
no variations work
* Vague directives produce vague results – be specific
* Verify file loading before assuming AI is ignoring
instructions
* Use diagnostic questions to isolate the problem
* Start simple, add complexity gradually
My variables aren’t persisting between sessions – why?
Quick Answer:
Variables only persist if you reload your CRAFT project files at
the start of each new session. AI chats are stateless—context
disappears when a chat ends unless you explicitly load your
project file (which contains your variables) in the new session.
Detailed Explanation:
Variable persistence is one of the most common CRAFT
misconceptions. Understanding how it actually works will solve
99% of persistence issues.
How CRAFT Persistence Actually Works
The Core Truth:
AI platforms don’t have built-in memory between chat sessions.
CRAFT solves this through manual file reloading.
The Persistence Flow:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: How Persistence Works Across Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 1:
Session 2:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Insight: Your PROJECT_VARIABLES section in your project
file is the persistence mechanism. The file persists, not the
AI’s memory.
Common Misconception
What Users Think Happens:
“I defined COMPANY_NAME = ‘Acme Corp’ in Session 1, so Session 2
should remember it.”
What Actually Happens:
Session 1 context is completely erased. Session 2 knows nothing
about Session 1 unless you reload the files.
The CRAFT Solution:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Variables in Project File Provide Persistence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PROJECT_VARIABLES = {
“COMPANY_NAME”: “Acme Corp”,
“PRODUCT”: “CloudSync Pro”,
“TARGET_AUDIENCE”: “IT managers”
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This file persists on your computer. You load it in every
session, giving the illusion of AI memory.
Why Variables Seem to Disappear
Scenario 1: Files Not Reloaded
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Files Not Reloaded Problem
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 1: Upload files → Define variables → Work
normally
Session 2: Don’t upload files → Variables don’t exist
Fix: Always reload files at session start:
#H->AI::Directive: (Execute CHAT-INIT recipe)
#H->AI::Context: (Project 025, session type: continue,
handoff: H003)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Scenario 2: Using Claude Projects Incorrectly
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Claude Projects Mistake
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Mistake: Attached files to one message, not to the
project
Result: Files available in that chat only, not across
all project chats
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: Upload files to the Project itself:
* Open Claude Project settings
* Upload files to project (not individual chats)
* Files now available in all chats within that project
Scenario 3: Modified Variables Not Saved
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Variable Changes Not Saved
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session 1: Change BUDGET = 50000 to BUDGET = 75000 in
chat
End session without updating project file
Session 2: BUDGET still = 50000 (because file wasn’t
updated)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: After modifying variables, update your actual .txt file:
1. Note the change in current session
2. Open your CFT-PROJ-XXX file in text editor
3. Update the variable value
4. Save the file
5. Next session will have the new value
The Handoff System for Continuity
CRAFT’s handoff system tracks what happened between sessions:
How It Works:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Handoff System for Session Continuity
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Execute HANDOFF_SNAPSHOT recipe)
HANDOFF_H001 = {
“session_summary”: “Created marketing strategy,
defined target segments”,
“current_state”: “Strategy approved, ready for
content creation”,
“next_steps”: [“Create social media content”,
“Draft email campaign”],
“key_decisions”: [“Target 5 industries instead of 3”]
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Start of Session 2:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Loading Previous Handoff
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Execute CHAT-INIT recipe)
#H->AI::Context: (Continue from handoff H001)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Platform-Specific Persistence Strategies
Claude (Best for Persistence):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Claude Projects Setup for Persistence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Setup:
Daily Use:
– Start new chat in project
– Files already loaded
– Work normally
– Variables available immediately
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ChatGPT:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: ChatGPT Persistence Strategy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Setup:
– No automatic persistence
– Must reupload files at each session start
Daily Use:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Gemini:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Gemini Persistence Strategy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Setup:
Daily Use:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Testing Persistence
Verification Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Testing Variable Persistence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TEST_PERSISTENCE = “Session_1_Value”
#H->AI::Directive: (Note TEST_PERSISTENCE value)
#H->AI::Question: (What is the value of
TEST_PERSISTENCE?)
Expected: “Session_1_Value”
If AI says it doesn’t know: Files weren’t loaded properly
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Updating Persisted Variables
Process:
1. During Session: Make note of variable changes
2. After Session: Open project file in text editor
3. Update File: Change variable values
4. Save File: Save updated .txt file
5. Next Session: Load updated file
Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Updating Variables Between Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BUDGET = 50000
#H->AI::Note: (Update BUDGET to 75000 in project file)
BUDGET = 75000 # Updated 2025-10-25
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Common Mistakes and Fixes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Common Persistence Mistakes and Solutions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Not reloading Variables Always load files
files undefined at session start
Editing in chat Changes don’t Edit actual .txt
only persist files between
sessions
Attaching vs Inconsistent Upload to Project
uploading availability (Claude) or
re-attach each
time
Wrong file Old values Check file
version present version number,
load latest
Expecting AI “Why doesn’t it Understand: files
memory remember?” provide
persistence, not
AI memory
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* AI chats are stateless – context erases between
sessions
* Variables persist in your PROJECT FILE, not in AI
memory
* You must reload files at the start of EVERY new
session
* Claude Projects offer automatic file persistence
across chats
* Handoff system documents session-to-session changes
* Variable updates must be made to actual .txt files to
persist
* Always verify file loading at session start
Related Topics:
* How do I organize my CRAFT project files?
* What are Variables in CRAFT and why do I need them?
* How do I integrate CRAFT with different AI platforms?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The AI seems confused by my CRAFT structure – what should I check?
Quick Answer:
Check four things in order: (1) files are actually attached and
readable, (2) comment formatting is correct, (3) no
contradictory instructions exist, and (4) structure isn’t overly
complex. Most “confusion” comes from formatting errors or files
not being loaded.
Detailed Explanation:
When AI seems confused by CRAFT structure, it’s usually a
technical issue, not a CRAFT comprehension problem. Here’s a
systematic diagnostic approach.
Diagnostic Step 1: Verify File Loading
The Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Test File Loading
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (List all CRAFT files you currently
have access to in this session)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Expected Response:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Expected AI Response
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
I have access to:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If AI Can’t List Them:
* Files weren’t attached properly
* Claude: Check if files are in the Project (not just
attached to one message)
* ChatGPT: Re-upload files to current chat
* Gemini: Verify Drive links are accessible
Fix Before Proceeding: Nothing else matters if files aren’t
loaded.
Diagnostic Step 2: Test Variable Recognition
The Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Test Variable Recognition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (What is the value of COMPANY_NAME?)
#H->AI::Question: (What is the value of PROJECT_NAME?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If AI Says “I Don’t Know”:
* Files are attached but not being parsed correctly
* Variable might not be defined in PROJECT_VARIABLES
section
* File format might have issues (wrong encoding,
invisible characters)
Fix:
1. Open project file in text editor
2. Verify variables are in PROJECT_VARIABLES section
3. Check for proper Python syntax:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Correct vs Incorrect Variable Syntax
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme Corp” # ✓ Correct
COMPANY_NAME = Acme Corp # ✗ Missing quotes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4. Re-save file as UTF-8 plain text
5. Re-upload to AIDiagnostic Step 3: Check Comment Formatting
Common Formatting Issues:
Issue: Invisible characters
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Invisible Character Problem
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create report)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Test:
Copy this working example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Working Comment to Copy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Test comment formatting)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Paste it in your file, modify only the content inside
parentheses.
Issue: Wrong spacing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Spacing Errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H -> AI :: Directive: (Wrong) # Extra spaces
#H->AI::Directive:(No space) # Missing space before
# parenthesis
#H->AI::Directive: (Correct) # Correct
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issue: Similar-looking characters
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Wrong Character Types
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive‥ (Using Japanese colon) # Wrong
#H->AI::Directive： (Using full-width colon) # Wrong
#H->AI::Directive: (Using standard colon) # Correct
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: Use only standard ASCII characters. When in doubt, copy
from working examples.
Diagnostic Step 4: Identify Contradictions
Example Contradiction:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Contradictory Instructions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create comprehensive detailed
analysis)
#H->AI::Constraint: (Keep response under 50 words)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why AI Gets Confused:
“Comprehensive detailed” suggests depth, “under 50 words”
forces brevity. AI doesn’t know which to prioritize.
Fix:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Clear, Non-Contradictory Instructions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Create concise analysis summary)
#H->AI::Constraint: (Keep response under 50 words)
#H->AI::Focus: (Prioritize key findings only)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Common Contradictions:
* “Detailed” + “brief”
* “Technical” for “non-technical audience”
* “Include everything” + “keep it short”
* “Professional tone” + “use casual language”
Prevention: Read through your complete prompt. Do any
instructions work against each other?
Diagnostic Step 5: Assess Complexity
Signs of Over-Complexity:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Over-Complex Structures
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class Campaign:
class Segment:
class Persona:
class Behavior:
class Touchpoint:
# 5 levels deep…
VAR_1 = “…”
VAR_2 = “…”
VAR_52 = “…”
def generate_content(param1, param2, param3, param4,
param5, param6, param7):
# With 15 nested conditions…
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI Confusion Signals:
* Asks for clarification on obvious things
* Mixes up related concepts
* Defaults to generic responses
* Struggles with context
Fix: Simplify
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Simplified Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme”
PRODUCT = “CloudSync”
AUDIENCE = “IT Managers”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rule: If your CRAFT structure is confusing to YOU, it’s
definitely confusing to AI.
Diagnostic Step 6: Check Comment Placement
Poor Placement:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Poor Comment Placement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Context: (This is for a technical audience)
[500 lines of variable definitions]
#H->AI::Directive: (Create documentation)
Context too far from directive—AI may miss the
connection
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Better Placement:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Good Comment Placement
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Variable definitions]
#H->AI::Context: (This is for a technical audience)
#H->AI::Directive: (Create documentation using
PRODUCT_NAME and FEATURES)
Context immediately before directive—clear relationship
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Best Practice: Group related comments together. Don’t scatter
them.
Diagnostic Step 7: Verify File Format
Format Issues:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Common File Format Problems
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Saved as .docx (Word format)
❌ Saved as .rtf (rich text)
❌ Contains formatting (bold, italic, colors)
❌ Wrong line endings causing parsing errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Verification:
1. Open file in basic text editor (Notepad, TextEdit)
2. If you see formatting issues or weird characters:
wrong format
3. Re-save as plain text (.txt)
4. Ensure UTF-8 encoding
Claude/ChatGPT Requirement: Plain text .txt files only.
Diagnostic Step 8: Test Incrementally
The Isolation Method:
Start Minimal:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Test 1 – Absolute Minimum
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme”
#H->AI::Question: (What is COMPANY_NAME?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If this works, gradually add:
Test 2: Add one more variable
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Test 2 – Add Variable
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme”
PRODUCT = “CloudSync”
#H->AI::Question: (What are COMPANY_NAME and PRODUCT?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Test 3: Add first function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Test 3 – Add Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Acme”
PRODUCT = “CloudSync”
def describe_product():
return f”{PRODUCT} by {COMPANY_NAME}”
#H->AI::Directive: (Execute describe_product function)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Continue: Add complexity one element at a time until something
breaks. That’s your problem element.
Diagnostic Step 9: Check for Python Syntax Errors
CRAFT uses Python-compatible syntax. Python errors confuse AI:
Common Syntax Errors:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Common Python Syntax Errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY = “Acme Corp
COMPANY = ‘Acme’s Product’ # Single quote inside
# single quotes
def my_function():
return “something” # Should be indented
def my_function()
return “something” # Missing colon after function
# definition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: Run your CRAFT file through a Python syntax checker (VS
Code, PyCharm, or online validator).
When to Start Fresh
Sometimes it’s faster to start over than debug:
Start Fresh If:
* You’ve tried 5+ fixes without success
* File has accumulated lots of changes/experiments
* You’re not sure what works anymore
* File is >500 lines without clear organization
Fresh Start Process:
1. Create new file: CFT-PROJ-XXX-v2a.txt
2. Copy ONLY working elements from old file
3. Test after each addition
4. Build cleanly from known-good foundation
Confusion Diagnostic Checklist
Run through this checklist when AI seems confused:
☐ Files actually attached/uploaded?
☐ AI can list the files when asked?
☐ AI recognizes at least one variable?
☐ Comment syntax exactly matches examples?
☐ No contradictory instructions?
☐ Structure reasonably simple?
☐ Comments placed near relevant directives?
☐ Files saved as plain .txt?
☐ No Python syntax errors?
☐ Tested with minimal example first?If ALL checkboxes pass and AI is still confused: Start a new
chat session (sometimes helps) or start fresh with new
simplified file.
Key Points:
* 95% of “AI confusion” is file loading or formatting
issues
* Always verify files are loaded before assuming CRAFT
problem
* Comment syntax must be exact – no variations
* Contradictory instructions paralyze AI decision-making
* Over-complexity causes confusion – simplify first
* Test with minimal examples, add complexity
incrementally
* Python syntax errors break CRAFT parsing
* When in doubt, start a fresh session or new file
Related Topics:
* The AI isn’t following my CRAFT instructions – what’s
wrong?
* What are the most common CRAFT mistakes and how do I
fix them?
* What should I do when CRAFT isn’t working as
expected?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What should I do when CRAFT isn’t working as expected?
Quick Answer:
Follow this sequence: (1) start a new chat session—this fixes
40% of issues immediately, (2) verify files are actually loaded,
(3) test with a minimal example, (4) simplify your structure,
(5) check the troubleshooting checklist, and (6) if still stuck,
create a new simplified project file and migrate working
elements gradually.
Detailed Explanation:
When CRAFT isn’t working, a systematic troubleshooting approach
saves time and frustration. Here’s the step-by-step process.
Step 1: Start a New Chat Session (Try This First)
Why This Works:
* Clears corrupted session state
* Removes accumulated context conflicts
* Resets AI’s understanding
* Fixes ~40% of issues immediately
How To Do It:
1. Note your problem in current session
2. Create handoff (if mid-project)
3. Start completely new chat
4. Reload all files fresh
5. Test if problem persists
What This Fixes:
* AI “stuck” on wrong interpretation
* Conflicting instructions from earlier in session
* Token budget issues
* Accumulated errors
Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: New Session Often Fixes Issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
User: [Complex 50-message conversation]
User: Why isn’t this working anymore?
Load files
#H->AI::Directive: (Execute CHAT-INIT recipe)
#H->AI::Context: (Project 025, continue from H005)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
When to Try This: Anytime something feels “off” or AI isn’t
responding as expected. Cost: 2 minutes. Success rate: ~40%.
Step 2: Verify File Loading
The Diagnostic:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Verify Files Are Loaded
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (List all CRAFT files you can see in
this session)
#H->AI::Question: (What is the value of PROJECT_NAME?)
#H->AI::Question: (What is the value of COMPANY_NAME?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Expected Responses:
* Files: Lists your 4 CRAFT files
* PROJECT_NAME: States the correct value
* COMPANY_NAME: States the correct value
If Any Fail:
Files aren’t actually loaded despite appearing attached.
Fixes by Platform:
Claude Projects:
1. Open Project settings
2. Verify files are uploaded to PROJECT (not just one
chat)
3. Check file names match what you think they are
4. Re-upload if necessary
ChatGPT:
1. Ensure files attached to CURRENT chat (not
previous chat)
2. Re-attach files
3. Verify file format is .txt
Gemini:
1. Verify Google Drive link permissions
2. Check link is “Anyone with link can view”
3. Try re-sharing link in chat
Step 3: Test With Minimal Example
The Process:
Strip everything down to absolute basics.
Minimal Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Minimal Test File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Test Company”
#H->AI::Directive: (What is the value of COMPANY_NAME?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If This Works:
Problem is in your complex structure, not CRAFT itself.
If This Fails:
Problem is with file loading or platform issue.
Gradual Rebuild:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Gradual Complexity Addition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPANY_NAME = “Test Company”
COMPANY_NAME = “Test Company”
PRODUCT_NAME = “Test Product”
COMPANY_NAME = “Test Company”
PRODUCT_NAME = “Test Product”
def describe():
return f”{PRODUCT_NAME} by {COMPANY_NAME}”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 4: Simplify Structure
Common Over-Complications:
Too Complex:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Overly Complex Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
class CampaignEngine:
class SegmentAnalyzer:
class PersonaBuilder:
class BehaviorTracker:
def analyze_touchpoint_sequence(self,
params):
# 100 lines of logic
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Simplified:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Simplified Structure
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CAMPAIGN_NAME = “Q2 Launch”
TARGET_SEGMENTS = [“Enterprise”, “Mid-market”]
KEY_MESSAGES = [“Reliability”, “Ease of use”]
#H->AI::Directive: (Create campaign content for Q2
Launch)
#H->AI::Context: (Targeting TARGET_SEGMENTS with
KEY_MESSAGES)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rule: If you’re confused by your own structure, simplify.
Step 5: Check Common Issues
Rapid Troubleshooting Checklist:
Syntax Issues:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Common Syntax Errors
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive (Missing colon)
#H->AI::Directive: Missing parentheses
#AI->H::Directive: (Wrong direction)
#H->AI::Directive: (Correct format)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Format Issues:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Format Checklist
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Check:
☐ Files are .txt (not .docx, .rtf)
☐ Plain text only (no formatting)
☐ UTF-8 encoding
☐ No invisible characters
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Logic Issues:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Logic Issues Checklist
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Check for contradictions:
☐ “Detailed” vs “Brief”
☐ “Technical” vs “Non-technical audience”
☐ “Include everything” vs “Keep short”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Variable Issues:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Variable Issues Checklist
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Check:
☐ Variables defined in PROJECT_VARIABLES section
☐ Proper Python syntax (quotes, equals signs)
☐ Consistent naming (no typos)
☐ Actually loading (test with question to AI)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 6: Platform-Specific Resets
Claude:
1. Leave current Project
2. Create new Project
3. Upload files fresh
4. Test in new environment
ChatGPT:
1. Start new chat (not within old thread)
2. Clear browser cache (sometimes helps)
3. Re-upload files
4. Test fresh
Gemini:
1. Re-upload files to new Google Drive folder
2. Generate new sharing links
3. Start new Gemini chat
4. Share new links
Step 7: Create Clean Project File
When Nothing Else Works:
Sometimes accumulated changes make files unmaintainable. Start
fresh.
Process:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Creating Clean Project File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 8: Diagnostic Questions to Ask
When to Ask AI:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Diagnostic Questions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (What CRAFT files do you see?)
#H->AI::Question: (Can you access my project
variables?)
#H->AI::Question: (Is there anything unclear about my
instructions?)
#H->AI::Question: (Are there any contradictions in my
directives?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI can often pinpoint the issue if you ask directly.
Step 9: Compare Against Working Example
The Method:
Find a session where CRAFT worked perfectly.
Compare:
* What files were loaded?
* What was the structure?
* How were directives formatted?
* What was different?
Example:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Comparing Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Loaded: All 4 files
Directive: Simple, clear
Result: Perfect output
Loaded: Same files, but different versions?
Directive: Complex, nested
Result: Confused output
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 10: Document and Learn
When You Fix an Issue:
Create a Note:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Troubleshooting Log
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TROUBLESHOOTING_LOG = {
“2025-10-25”: “AI confused – fixed by starting new
session”,
“2025-10-26”: “Variables not loading – file wasn’t
actually attached”,
“2025-10-27”: “Syntax error in comment – missing
colon”
}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why: You’ll encounter similar issues in the future. Your log
helps solve them faster.
Troubleshooting Decision Tree
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Troubleshooting Decision Tree
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CRAFT not working?
├─ Step 1: Start new chat session
│ └─ Fixed? STOP (40% of issues)
│
├─ Step 2: Verify files loaded
│ └─ Files not loaded? Fix loading → STOP
│
├─ Step 3: Test minimal example
│ ├─ Minimal works? → Problem is complexity →
│ │ Simplify
│ └─ Minimal fails? → Problem is platform/files →
│ Fix loading
│
├─ Step 4: Check syntax
│ └─ Syntax wrong? Fix syntax → STOP
│
├─ Step 5: Look for contradictions
│ └─ Found contradictions? Resolve → STOP
│
├─ Step 6: Platform-specific reset
│ └─ Try different platform/fresh environment
│
└─ Step 7: Create clean file
└─ Start fresh, migrate working elements
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
When to Ask for Help
After trying:
✓ New chat session
✓ Verified file loading
✓ Tested minimal example
✓ Checked syntax
✓ Simplified structure
✓ Platform reset
If still stuck: Problem might be:
* Edge case in your specific use case
* Platform-specific bug
* Unusual file format issue
* Complex interaction between components
Where to get help:
* CRAFTFramework.ai community
* Platform-specific support (Claude/ChatGPT)
* CRAFT documentation FAQ
Key Points:
* 40% of issues fixed by simply starting a new chat
session
* File loading problems are #1 cause of CRAFT “not
working”
* Test with minimal examples to isolate problems
* Simplification often fixes mysterious issues
* Platform-specific resets can resolve persistent
problems
* Keep troubleshooting log for future reference
* When stumped, create clean new file and migrate
working elements
* Starting a new session is free, quick, and
surprisingly effective
Related Topics:
* The AI isn’t following my CRAFT instructions –
what’s wrong?
* What are the most common CRAFT mistakes and how do I
fix them?
* The AI seems confused by my CRAFT structure – what
should I check?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What if the AI cannot read the text files? Why does this happen?
Quick Answer:
Any AI can occasionally have trouble reading files—this
situation is rare and only happens when the AI platform is
experiencing technical issues with file processing. Test by
asking the AI to summarize your attached files; the AI will
clarify if files are readable or not.
Detailed Explanation:
File reading issues are uncommon but can occur across any AI
platform. Understanding why this happens and how to diagnose it
helps you determine if the problem is temporary or requires
action.
Why File Reading Fails
Platform-Level Issues (Most Common):
* Server load: High platform usage can temporarily
affect file processing
* Service disruptions: Intermittent technical issues on
AI provider’s end
* API timeouts: File processing taking longer than
allowed time
* Temporary bugs: Platform updates sometimes introduce
temporary file-handling issues
File-Level Issues:
* Corrupted upload: File didn’t transfer completely
* Encoding problems: Unusual character encoding AI
can’t parse
* Format issues: File appears as .txt but has hidden
formatting
* Size limitations: File exceeds platform’s processing
capability
Session-Level Issues:
* Cache problems: Browser or app cache interfering
* Network interruption: Upload interrupted mid-transfer
* Multiple upload attempts: Confused state from
repeated uploads
How to Diagnose File Reading Issues
The Simple Test:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Testing File Readability
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Directive: (Please provide a brief summary of
the CRAFT files I just attached)
#H->AI::Question: (Can you see:
CFT-PROJ-025_MARKETING-v1c.txt?)
#H->AI::Question: (What is the first line of that
file?)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Expected AI Responses:
If Files Are Readable:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: AI Response When Files Are Readable
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
I can see your CRAFT project files:
The first line is: “# CRAFT PROJECT FILE…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If Files Are NOT Readable:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: AI Response When Files Are Not Readable
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
I apologize, but I’m having difficulty accessing the
files you’ve attached.
I can see that files were uploaded, but I cannot read
their contents currently.
or
I don’t see any attached files in our current
conversation. Could you verify they were uploaded
successfully?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Immediate Fixes to Try
Fix 1: Simple Retry
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Simple Retry Process
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Success Rate: ~30% (works for temporary glitches)
Fix 2: Start New Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: New Session Process
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Success Rate: ~40% (clears session-level issues)
Fix 3: Browser/App Refresh
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Refresh Process
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Success Rate: ~20% (fixes cache issues)
Fix 4: Different Browser/Device
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Alternative Browser/Device
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Success Rate: ~15% (works for browser-specific bugs)
Fix 5: File Re-Save
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: File Re-Save Process
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Success Rate: ~10% (fixes corrupted files)
Platform-Specific Considerations
Claude:
* Generally excellent file handling
* Project files persist, reducing repeat upload issues
* If files won’t load, check Project file limit (50
files max)
ChatGPT:
* Occasionally has file reading issues during high
load
* No persistence—must reupload each session
* Try GPT-4 vs GPT-4 Turbo if issues persist
Gemini:
* Uses Google Drive links for larger files
* File reading depends on Drive permissions
* Check sharing settings: “Anyone with link can view”
When File Reading Issues Are Persistent
If None of the Quick Fixes Work:
Option 1: Copy-Paste Method
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Copy-Paste Method
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Instead of attaching files:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Advantages:
* Bypasses file upload system
* Works when file attachments fail
* Immediate availability
Disadvantages:
* Messier chat interface
* Uses more tokens
* Not practical for very large files
Option 2: Simplified File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Create Simplified Version
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Create minimal version:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Option 3: Alternative Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Try Alternative Formats
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If .txt fails:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Determining If It’s a CRAFT Issue or Platform Issue
Test With Non-CRAFT File:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Testing with Simple File
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If AI can’t read this either:
→ Platform issue, not CRAFT issue
→ Try different browser/device/time
If AI CAN read simple file but not CRAFT file:
→ Something specific to your CRAFT file
→ Check encoding, formatting, file size
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Reading vs. File Recognition
Important Distinction:
File Recognition (AI sees file exists):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: File Recognition
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI: “I see you’ve attached
CFT-PROJ-025_MARKETING-v1c.txt…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Reading (AI can access contents):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: File Reading
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI: “Your project file defines COMPANY_NAME as ‘Acme
Corp’…”
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You Need Both. Sometimes AI recognizes file but can’t read
contents.
If AI Recognizes but Can’t Read:
* Encoding issue
* Format issue
* Platform processing issue
* File corruption
Preventive Measures
To Minimize File Reading Issues:
When to Wait vs. When to Act
Wait a Few Minutes If:
* First time experiencing the issue
* Platform status shows known issues
* Error message suggests temporary problem
Act Immediately If:
* You need to work NOW
* Problem persists across multiple attempts
* Files previously worked fine, suddenly don’t
Communicating With AI About File Issues
Effective Communication:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXAMPLE: Asking AI About File Issues
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#H->AI::Question: (I’ve attached 4 CRAFT files. Can you
confirm you can read them?)
#H->AI::Question: (If you cannot read them, please tell
me specifically what you see)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AI Will Tell You:
* “I see 4 files and can read all of them…”
→ ✅ Working
* “I see 4 files but cannot access contents…”
→ ❌ Reading issue
* “I don’t see any attached files…”
→ ❌ Upload failed
File Reading Troubleshooting Flowchart
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File Reading Troubleshooting Flow
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Can AI read files?
│
├─ No – AI says “I don’t see files”
│ └─ Upload failed → Re-upload → Test
│
├─ No – AI says “I see files but can’t read”
│ ├─ Try new session → Test
│ ├─ Try different browser → Test
│ ├─ Try copy-paste method → Test
│ └─ File format issue → Re-save as plain text →
│ Test
│
└─ Yes – AI summarizes files correctly
└─ ✅ Proceed with CRAFT work normally
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Points:
* File reading issues are rare but do occur on any
platform
* Simple test: Ask AI to summarize your files
* 70% of file reading issues fixed by retry, new
session, or browser refresh
* Platform issues (server load, bugs) are most common
cause
* Copy-paste method bypasses file upload system when
needed
* File recognition ≠ file reading – AI must actually
access contents
* Test files immediately after upload, don’t assume
they loaded
* Keep files under 500KB, use UTF-8 encoding for best
compatibility
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━