Skip to content

Commit bc9a0c5

Browse files
hoomanhooman
committed
Merge: add Guide for Analysts (Chat IR)
2 parents de6ecd8 + 10f1c79 commit bc9a0c5

3 files changed

Lines changed: 323 additions & 1 deletion

File tree

‎CLAUDE_SESSION_LOG.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -316,4 +316,40 @@ in Chat's IR. Also committed this session:
316316
- `CLAUDE.md` added at repo root: bootstrap pointer for fresh Code sessions
317317
(reads `docs/CLAUDE_CODE_INSTRUCTIONS.md`)
318318

319+
### 2026-03-05 — Chat — Integration Request
320+
321+
**Session:** GUIDE_ANALYSTS.md creation
322+
**Summary:** Created `docs/GUIDE_ANALYSTS.md` (deferred from repo reorg Phase 4)
323+
and updated README link from "forthcoming" to live.
324+
325+
**New files:**
326+
- `docs/GUIDE_ANALYSTS.md` — audience guide for policy professionals, journalists,
327+
and researchers. Covers: framework navigation (ITB/ISA/briefs layers), reading
328+
epistemic tags and cross-references, using findings in own work (citation format,
329+
scope limits), challenging the framework (5 productive critique types),
330+
contributing without code (Farsi sources, SME review, case analysis, gap fills).
331+
332+
**Updated files:**
333+
- `README.md`: replaced "A Guide for Analysts is forthcoming" with live link
334+
to `docs/GUIDE_ANALYSTS.md`
335+
336+
**Entity counts:** No YAML changes. All entity counts in public docs remain accurate.
337+
338+
**Action for Code:** Both files are already edited on disk. Just commit.
339+
340+
**Ambiguities:** None.
341+
342+
### 2026-03-05 — Code — Integration Complete
343+
344+
**GUIDE_ANALYSTS.md committed.** Applied Chat's IR:
345+
346+
- `docs/GUIDE_ANALYSTS.md`: new file — analyst guide for policy professionals,
347+
journalists, and researchers (framework navigation, epistemic tags,
348+
cross-references, citation format, challenging the framework, contributing
349+
without code). Completes deferred Phase 4 deliverable from repo reorg.
350+
- `README.md`: replaced "forthcoming" placeholder with live link to
351+
`docs/GUIDE_ANALYSTS.md`.
352+
353+
**Validation:** 247 entries PASS; 17 briefs PASS. No YAML changes in this IR.
354+
319355
<!-- END LOG -->

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ See [Contributing](docs/CONTRIBUTING.md).
122122
build their own analytical projects using the same pipeline.
123123
See [Guide for Engineers](docs/GUIDE_ENGINEERS.md).
124124
Traditional analysts can engage with the methodology without touching code.
125-
A Guide for Analysts is forthcoming.
125+
See [Guide for Analysts](docs/GUIDE_ANALYSTS.md).
126126

127127
---
128128

‎docs/GUIDE_ANALYSTS.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Guide for Analysts
2+
3+
**Using the ITP Framework for Policy, Research, and Reporting**
4+
5+
---
6+
7+
## What This Guide Covers
8+
9+
This guide is for policy professionals, journalists, researchers, and anyone
10+
working on Iran who wants to use this framework's analytical output — without
11+
needing to understand the build pipeline, YAML files, or code.
12+
13+
If you want to understand how the technical machinery works or fork the
14+
repository for your own project, see [Guide for Engineers](GUIDE_ENGINEERS.md).
15+
16+
---
17+
18+
## How the Framework Is Organized
19+
20+
The project produces three layers of analysis, each building on the one below:
21+
22+
**Layer 1: The Iran Transition Baseline (ITB)** is the structural foundation.
23+
It maps how the regime actually works across eight pillars — constitutional
24+
architecture, security apparatus, economics, international alignment, domestic
25+
society, transition dynamics, nuclear program, and information environment.
26+
Twenty-two analytical modules, each with explicit section numbering and
27+
cross-references.
28+
29+
**Layer 2: The Iran Stress Architecture (ISA)** identifies where the system
30+
is vulnerable and where Western analysis consistently breaks. It contains
31+
three entity types:
32+
33+
- **Traps** are circular logic structures that catch policymakers. A trap
34+
documents its mechanism, its circular structure, what would break the
35+
circularity, and historical cases where the same pattern has played out.
36+
Fourteen documented.
37+
38+
- **Observations** are "so-what" findings that emerge from cross-referencing
39+
ITB modules. Each one states a diagnosis (what is true) and a strategic
40+
implication (what it means for planning). Thirty logged.
41+
42+
- **Scenarios** model transition and conflict pathways with probability
43+
ranges, leading indicators, and cross-referenced variables. Twelve modeled.
44+
45+
**Layer 3: Convergence Briefs** translate framework findings into focused,
46+
publication-length analysis. Each brief isolates a specific structural problem
47+
and traces its implications. These are the primary entry point for most
48+
readers — start here and follow cross-references deeper into the framework
49+
when you need the underlying evidence.
50+
51+
Supporting these layers: eighty-six tracked **variables** (structural
52+
conditions, dynamic indicators, trigger thresholds) and fifty-seven registered
53+
**research gaps** (open questions with priority and status tracking).
54+
55+
---
56+
57+
## How to Read Framework Output
58+
59+
### Epistemic Tags
60+
61+
Every analytical claim in the framework carries an inline tag:
62+
63+
| Tag | What It Means | How Much Weight It Bears |
64+
|-----|---------------|------------------------|
65+
| `[Fact — High]` | Directly verifiable, multiple independent sources | Treat as established |
66+
| `[Inference — Med]` | Reasoned from established facts, logic chain stated | Reliable but dependent on premises |
67+
| `[Uncertain — Low]` | Single source, contested, or extrapolated | Use cautiously; may change with new evidence |
68+
| `[Speculation]` | Forward projection, acknowledged hypothesis | Do not cite as a finding |
69+
70+
The tag tells you at a glance whether a specific claim can support the weight
71+
of a policy recommendation or a published assertion. Traditional analytical
72+
products rarely make this visible — you would need to trace the sourcing
73+
appendix to make the same judgment.
74+
75+
**Practical rule:** If you are citing a framework finding in your own work,
76+
cite the tag alongside it. A finding tagged `[Inference — Med]` is an
77+
analytical conclusion with stated reasoning — credible but conditional. A
78+
finding tagged `[Fact — High]` is sourced bedrock. The distinction matters
79+
for your readers as much as for ours.
80+
81+
### Cross-References
82+
83+
Framework documents use a consistent reference format: `MODULE-SECTION`
84+
(e.g., ITB-A10 S3.4, ISA-TRAPS Trap 8). When you encounter a
85+
cross-reference, it points to a specific module and section in the
86+
structured database. In the published output (PDFs and markdown), these
87+
references link to or name the relevant document.
88+
89+
Cross-references are not decorative. They trace the evidence chain — the
90+
claim you are reading rests on analysis developed elsewhere in the
91+
framework, and the reference tells you exactly where to verify or
92+
challenge it.
93+
94+
### Source Hierarchy
95+
96+
The project applies a five-tier source taxonomy:
97+
98+
1. **Regime primary sources** — KHAMENEI.IR, official institutional output,
99+
seminary publications, IRGC-affiliated media
100+
2. **Human rights monitoring organizations** — HRANA, Amnesty, CHRI
101+
3. **Academic Iran studies** — peer-reviewed research
102+
4. **Diaspora investigative outlets** — with transparent sourcing methodology
103+
5. **Unverified or single-source**
104+
105+
Two points that matter for how you use the output:
106+
107+
First, regime primary sources are not treated as factual reporting. They are
108+
treated as signaling data — what the regime chooses to say, to whom, and when.
109+
When the framework cites KHAMENEI.IR, the analytical signal is the publication
110+
decision, not the content's truth value.
111+
112+
Second, Wikipedia is excluded as a primary or corroborating source for Iran
113+
content. This is a deliberate methodological choice based on documented
114+
state-affiliated manipulation of Iran-related Wikipedia articles.
115+
116+
---
117+
118+
## How to Navigate the Framework
119+
120+
### Starting from a Policy Question
121+
122+
If you have a specific question — *Can a nuclear deal hold? What happens
123+
after Khamenei? Will the IRGC accept a transition?* — the most efficient
124+
path is:
125+
126+
1. **Start with the briefs.** Scan the brief titles for the one closest to
127+
your question. Each brief is self-contained with its own introduction and
128+
evidence base.
129+
130+
2. **Follow cross-references into the ITB/ISA.** The brief will cite specific
131+
modules, observations, and traps. These give you the underlying structural
132+
analysis.
133+
134+
3. **Check the variables and gaps.** The variable tables show you what the
135+
project is tracking and at what confidence. The gap registry shows you
136+
what the project does not know — and therefore where its conclusions are
137+
most vulnerable.
138+
139+
### Starting from a Research Interest
140+
141+
If you are working on a specific topic — IRGC economics, succession
142+
dynamics, Chinese weapons transfers, the eschatological faction — the ITB
143+
modules are your entry point. Each module covers a defined analytical domain
144+
with section numbering that allows precise citation.
145+
146+
### Starting from Methodological Interest
147+
148+
If you want to evaluate the framework itself — its assumptions, blind spots,
149+
or analytical choices — start with [Methodology](METHODOLOGY.md). It
150+
describes what the project does differently from traditional analytical
151+
approaches and explicitly invites critique.
152+
153+
---
154+
155+
## Using Framework Findings in Your Own Work
156+
157+
### Citation
158+
159+
Framework output is published under CC BY-SA 4.0. You may cite, excerpt,
160+
and build on any finding with attribution. Suggested citation format:
161+
162+
> Iran Transition Project, "[Module or Brief Title]," version [X.X],
163+
> [date], https://github.com/IranTransitionProject/framework
164+
165+
When citing a specific claim, include its epistemic tag. This preserves
166+
the evidence-quality signal for your readers and distinguishes your use
167+
of the framework from uncritical adoption.
168+
169+
### What the Framework Can and Cannot Do for You
170+
171+
**It can** provide a structured analytical baseline — a map of who holds
172+
power, what binds the system, where the stress points are, and what
173+
historical patterns suggest about transition dynamics. If you are writing
174+
analysis, making policy recommendations, or briefing decision-makers, the
175+
framework gives you a cross-referenced evidence base to work from.
176+
177+
**It cannot** replace classified intelligence, human source networks, or
178+
real-time operational data. The project relies entirely on open sources.
179+
Operational military details, internal regime communications, and signals
180+
intelligence are outside its reach. The framework structures and validates
181+
the analytical interpretation — it does not generate the raw intelligence.
182+
183+
**It cannot** tell you what to recommend. The framework is factionally
184+
neutral by design. It maps what must be true regardless of who governs,
185+
not what policy outcome is preferable. Your policy judgment is yours.
186+
187+
### Challenging the Framework
188+
189+
The framework is designed to be challenged, not adopted wholesale. The
190+
most productive challenges target:
191+
192+
- **Confidence bands that seem too high.** Where does the evidence not
193+
support the stated confidence? Where should `[Inference — Med]` be
194+
`[Uncertain — Low]`?
195+
196+
- **Missing variables or gaps.** What is the framework not tracking that
197+
it should be? What open questions are unregistered?
198+
199+
- **Structural blind spots.** What categories of information does the
200+
framework's architecture systematically exclude? Not individual errors,
201+
but patterns.
202+
203+
- **Source gaps.** Where does the analysis rest entirely on English-language
204+
sourcing for a topic that requires Farsi or Arabic sources?
205+
206+
- **Trap or scenario completeness.** Are there circular logic structures
207+
or transition pathways the framework has not identified?
208+
209+
These are the critiques that improve the framework. Challenges that
210+
substitute a preferred political outcome for analytical neutrality, or
211+
that assert conclusions without sourcing, do not meet the project's
212+
standards — but methodological disagreements always do.
213+
214+
---
215+
216+
## Contributing Without Code
217+
218+
You do not need to touch a YAML file, run a build script, or open a
219+
terminal to contribute to this project. The highest-value analytical
220+
contributions are:
221+
222+
**Persian-language source integration.** The framework's multilingual
223+
mandate is only as strong as the sources it can access. If you read
224+
Farsi and can identify regime primary sources, seminary publications,
225+
or institutional media that bear on framework findings, that is a
226+
high-priority contribution.
227+
228+
**Subject matter review.** Read a module or brief in your area of
229+
expertise. Where is it wrong? Where is it undersourced? Where does the
230+
confidence band not match the evidence? A structured critique —
231+
identifying the specific claim, its current tag, and what evidence
232+
would change it — is more valuable than general feedback.
233+
234+
**Historical case analysis.** The framework uses historical parallels
235+
for transition dynamics (South Africa, Chile, Soviet Union, others).
236+
If you have expertise in a relevant case and can identify where the
237+
parallel holds or breaks, that directly strengthens the scenario
238+
modeling.
239+
240+
**Gap resolution.** The research gap registry is public. If you have
241+
access to information that could fill an open gap — a source, a data
242+
point, a subject matter judgment — submit it through the channels below.
243+
244+
### How to Submit
245+
246+
All of these can be submitted without touching the repository:
247+
248+
- **Public discussion:** [GitHub Discussions](../../discussions)
249+
(Feedback & Critique category)
250+
- **Private submissions:** [irantransitionproject.org/submit](https://irantransitionproject.org/submit)
251+
- **Email:** [admin@irantransitionproject.org](mailto:admin@irantransitionproject.org)
252+
253+
If your contribution involves structured data (new variables, gap fills,
254+
observation proposals), the project maintainers will handle the YAML
255+
integration. You provide the analysis; the pipeline handles the formatting.
256+
257+
See [Submissions Protocol](SUBMISSIONS.md) for detailed guidance on what
258+
to include with different types of contributions.
259+
260+
---
261+
262+
## A Note on AI-Assisted Analysis
263+
264+
This project uses Claude (Anthropic) as a research assistant. The full
265+
details are in [Methodology](METHODOLOGY.md) and
266+
[Working with LLMs](WORKING_WITH_LLMS.md), but the key points for
267+
analysts evaluating the framework's output:
268+
269+
The AI accelerates research — multilingual source retrieval, structured
270+
data maintenance, draft generation — but it is not a source. Every claim
271+
in the framework requires independent sourcing and epistemic tagging
272+
per the standards described above. AI-generated content that cannot be
273+
sourced is not published.
274+
275+
The instruction files that govern AI behavior are public. If you suspect
276+
the AI-assisted workflow introduces bias, you can read the exact
277+
constraints it operates under and critique them. This is by design.
278+
279+
---
280+
281+
## Questions
282+
283+
- **Analytical:** [GitHub Discussions](../../discussions) or
284+
[admin@irantransitionproject.org](mailto:admin@irantransitionproject.org)
285+
- **Technical:** See [Guide for Engineers](GUIDE_ENGINEERS.md)
286+
- **Submissions:** See [Submissions Protocol](SUBMISSIONS.md)

0 commit comments

Comments
 (0)