@rubytech/create-realagent 1.0.406

package/payload/premium-plugins/writer-craft/references/scene-analysis-framework.md

@@ -0,0 +1,95 @@
+# Scene Analysis Framework
+
+## The Scene Card
+
+Every scene must justify its existence. The Scene Card is the diagnostic tool:
+
+| Element | Question | Why It Matters |
+|---------|----------|---------------|
+| **External event** | What happens? State it in one sentence. | The visible plot action |
+| **Internal meaning** | How does this force the protagonist's internal struggle forward? | THE critical test — if this is empty, the scene is dead weight |
+| **Urgency hook** | What question does this raise that pulls the reader into the next scene? | Creates forward momentum via dopamine |
+| **Cause** | What prior event made this scene necessary? | Ensures causal chain integrity |
+| **Effect** | What must happen next because of this scene? | Ensures forward momentum |
+
+## Scene Entry and Exit
+
+### Enter Late
+The scene should begin as close to its core event as possible. Not the approach to the restaurant — the conversation at the table. Not waking up and getting dressed — the moment the day goes wrong.
+
+### Exit Early
+The scene should end the moment its work is done. Not the drive home — the decision made. Not the aftermath — the turning point. Leave the reader with unresolved tension that pulls them into the next scene.
+
+## Internal Pattern Within the Scene
+
+Every scene should contain the four-beat internal pattern:
+
+1. **Action** — Something happens (external event)
+2. **Reaction** — The protagonist responds emotionally (internal response)
+3. **Decision** — The protagonist decides what to do next (choice)
+4. **New Action** — The protagonist acts on the decision (external consequence)
+
+This pattern may repeat multiple times within a single scene, at different scales. The reader tracks this rhythm unconsciously. When it breaks — when a character acts without reacting, or reacts without deciding — the reader disconnects.
+
+## Conflict Within the Scene
+
+### The Scene-Level "Versus"
+Every scene needs its own source of tension — a specific rock and hard place for the protagonist in this moment. This may be:
+- A direct confrontation with the antagonist
+- An internal dilemma (desire vs. misbelief)
+- A practical obstacle that tests the protagonist's resources
+- Social pressure that threatens to expose the protagonist's secret or flaw
+
+### Conflict Must Come From Character
+The best scene-level conflict arises from who the protagonist is — their misbelief creates the trap they're in. External obstacles imposed without connection to the protagonist's inner world feel arbitrary.
+
+### Escalation Within the Scene
+Even within a single scene, the stakes should shift — ideally upward. Each exchange, each beat, each revelation should raise the pressure. A scene that stays at the same level of tension throughout feels flat.
+
+## Emotional Presence
+
+### The Protagonist Must Be Emotionally Present
+Every event must register in the protagonist. If they witness something and have no response, the reader's mirror neurons have nothing to latch onto. Meaning collapses.
+
+### Show, Don't Label
+Not "she was afraid" but the specific physical, cognitive, and behavioural response that shows fear in this character in this moment. Different people express the same emotion differently — the response must be specific to this protagonist.
+
+### Body Language as Subtext
+Physical responses communicate what the character might never say. A character who says "I'm fine" while gripping the armrest hard enough to whiten their knuckles is telling two stories. The reader trusts the body over the words.
+
+## Prose Craft in the Scene
+
+### Rhythm Should Match Register
+Fast, staccato sentences for action and shock. Slower, flowing sentences for reflection and grief. The scene's emotional content should be embodied in its prose rhythm.
+
+### Sensory Detail Must Earn Its Place
+Every sensory detail should do at least one of:
+- Reveal character (what the protagonist notices tells us who they are)
+- Advance story (the detail has consequences later)
+- Illuminate theme (the detail carries symbolic weight)
+
+Details that are only atmospheric — that create setting without meaning — are clutter.
+
+### POV Consistency
+Check for one-sentence slips into another character's thoughts. In limited third person, the protagonist cannot know what another character is thinking or feeling — only what they observe.
+
+## Scene-Level Diagnostic
+
+### Does This Scene Earn Its Place?
+- [ ] Can you fill in all five Scene Card elements?
+- [ ] If you removed this scene, would the causal chain break?
+- [ ] Does this scene change something — advance the protagonist's internal struggle?
+
+### Is the Scene Engaging?
+- [ ] Does it enter late and exit early?
+- [ ] Is the internal pattern (action → reaction → decision → action) running?
+- [ ] Is there scene-level conflict specific to this moment?
+- [ ] Do stakes shift within the scene?
+- [ ] Does the scene end with an unresolved question?
+
+### Is the Prose Serving the Scene?
+- [ ] Does rhythm match emotional register?
+- [ ] Is the protagonist emotionally present throughout?
+- [ ] Are sensory details earning their place?
+- [ ] Is POV consistent — no accidental slips?
+- [ ] Is exposition integrated, not dumped?

package/payload/premium-plugins/writer-craft/references/self-editing.md

@@ -0,0 +1,89 @@
+# Self-Editing
+
+## Why Self-Editing Cannot Replace Professional Editing
+
+Authors cannot see their own work objectively. The blind spots created by familiarity are precisely what outside readers can address. Self-editing done well makes every subsequent editorial pass more productive — but it is no substitute for professional editorial input.
+
+Budget for editing as a production cost, not as an optional luxury.
+
+## The Successive Passes Method
+
+Work through the manuscript at decreasing levels of scale. Each pass focuses on one level:
+
+### Pass 1: Structure (Developmental)
+- Does the whole thing work? Read it through without stopping to fix sentences.
+- Are the parts in the right order?
+- Is anything missing? Is anything superfluous?
+- In fiction: is the internal story driving the plot? Is the protagonist active?
+- In nonfiction: is the argument clear and does it build?
+- Mark big-picture problems. Do not fix prose yet.
+
+### Pass 2: Chapter / Section
+- Does each chapter earn its place?
+- Does each chapter advance the story or argument?
+- Are there chapters that repeat what earlier chapters established?
+- Do chapters end at points that propel the reader forward?
+- Is the pacing right — neither rushed nor dragging?
+
+### Pass 3: Scene / Paragraph
+- Does each scene touch the third rail (the protagonist's internal struggle)?
+- Does each paragraph lead to the next?
+- Are there paragraphs that could be cut without loss?
+- Is exposition integrated into scenes, or dumped in blocks?
+- Are transitions smooth? Does the reader always know where they are?
+
+### Pass 4: Sentence
+- Is each sentence clear, necessary, and well-constructed?
+- Are there hedging adverbs, empty intensifiers, clichés?
+- Is the sentence variety appropriate?
+- Is the tonal register consistent?
+- Do long sentences carry the reader, or lose them?
+
+### Pass 5: Word
+- Is each word earning its place?
+- Can adjectives be absorbed into stronger nouns?
+- Can adverbs be absorbed into stronger verbs?
+- Are there qualifier ticks (just, very, kind of, sort of)?
+- Is the vocabulary level consistent and appropriate?
+
+## Self-Editing Techniques
+
+### Read Aloud
+The single most effective self-editing technique. Reading aloud reveals:
+- Awkward rhythms and clunky sentences
+- Missing words and wrong words
+- Passages that are too long or too convoluted
+- Dialogue that sounds unnatural
+- Repetition that the eye skips but the ear catches
+
+### Print and Read on Paper
+Changing the physical medium changes your relationship to the text. Errors and weaknesses visible on paper are often invisible on screen.
+
+### Read Backwards
+Read sentence by sentence from the end of the chapter to the beginning. This breaks the flow of expectation, forcing you to evaluate each sentence on its own merits rather than riding the momentum of the narrative.
+
+### Time Away
+The longer you can leave between writing and revising, the more clearly you see. A day is better than an hour. A week is better than a day. A month is better than a week. The goal is to read as a reader, not as the writer who knows what they meant.
+
+### Beta Readers
+Seek honest developmental feedback before investing time in line editing. There is no point polishing sentences in a chapter that needs to be restructured or cut.
+
+Choose beta readers who:
+- Represent your target audience
+- Will be honest, not just supportive
+- Can articulate why something works or doesn't (not just "I liked it" or "I didn't")
+- Understand the difference between their preferences and the book's needs
+
+### The Author's Most Common Blind Spots
+
+1. **Assuming the reader knows what you know** — the curse of knowledge. You wrote the backstory; you know the world; you understand the character's motivation. The reader doesn't.
+
+2. **Attachment to material that doesn't serve the story** — scenes, characters, research, and passages that represent real work and real quality but don't belong in this book.
+
+3. **Over-explaining** — providing more context than the reader needs, often because the writer isn't confident the point has landed.
+
+4. **Under-explaining** — skipping steps that feel obvious to the writer but aren't obvious to the reader.
+
+5. **Consistency errors** — the details that shift subtly between drafts (eye colour, timeline, geography, character names).
+
+6. **Pacing deafness** — inability to feel where the book slows down, often because the writer finds the material interesting regardless of whether it moves the story forward.

package/payload/premium-plugins/writer-craft/references/sound-and-rhythm.md

@@ -0,0 +1,64 @@
+# Sound, Rhythm, and Sentence Variety — Steering the Craft
+
+## Sound Is Primary
+
+The basic elements of language are physical — noise, sound, silence, rhythm. These matter in prose just as much as in poetry, though prose's sound effects are usually subtle and irregular. A good writer has a mind's ear. The common critical terms for weak prose — dull, choppy, droning, jerky, feeble — are all faults of sound.
+
+The chief duty of a narrative sentence is to lead to the next sentence. It does this through pace, movement, and rhythm.
+
+### Training the Mind's Ear
+- Read prose aloud, or read it silently with full auditory attention
+- Listen to what your own prose sounds like as you write it
+- When something sounds wrong, it is wrong — even if you can't name the problem
+- Language can express delight in itself, as music does — "poetry isn't the only kind of writing that can sound gorgeous"
+
+### Elements of Sound
+- **Onomatopoeia** — words that sound like what they mean (sizzle, hiss, slurp, crack)
+- **Alliteration** — repetition of initial sounds (not just identical letters — identical sounds)
+- **Cadence** — the rise and fall of sentence rhythm, created by the pattern of stressed and unstressed syllables
+- **Silence** — what is left out; pauses created by punctuation, paragraph breaks, white space
+
+## Sentence Length and Variety
+
+### The Core Principle
+There is no optimum sentence length. The optimum is **variety**. Rhythm in prose depends fundamentally on the contrast and interplay between sentences of different lengths.
+
+### Short Sentences
+- Highly effective in the right place — for emphasis, impact, sudden revelation
+- Prose consisting entirely of short, syntactically simple sentences is monotonous, choppy, and irritating
+- The myth that short sentences are "more like speech" is wrong — people often use more complex sentences when speaking than when writing
+
+### Long Sentences
+- Need careful construction — clear connections, solid architecture — so they flow and carry the reader rather than losing them
+- A sentence so grand it stops the story is not working as a narrative sentence
+- The proper beauty and power of prose is in the work as a whole, not in individual show-off sentences
+- Long sentences can: build tension, accumulate emotional weight, enact a physical experience (a jolting journey, a flowing river, a gathering storm)
+
+### Common Sentence Problems
+
+**Conjunctivitis**: Stringing short sentences together with conjunctions ("and then... and then... and so... but then"), creating a childish, droning effect.
+
+**Misplacement**: Parts of the sentence in the wrong order, creating ambiguity or absurdity. ("Walking down the street, the trees were beautiful" — the trees are walking.)
+
+**Danglers**: Modifying phrases attached to the wrong noun. ("After rotting in the cellar for three weeks, my sister brought up some oranges.")
+
+## Rhythm and Emotional Register
+
+Rhythm should match and embody the emotional content:
+- Fast, staccato rhythm for action, urgency, shock
+- Slower, rolling rhythm for reflection, grief, beauty
+- Varied rhythm for conversation, ordinary life, complexity
+- A sudden short sentence after long ones creates emphasis through contrast
+- A long sentence after short ones creates a feeling of expansion or accumulation
+
+### Rhythmic Variety in Practice
+Map the sentence lengths in a passage. If they're all similar, the passage will sound monotonous regardless of content. The interplay of short and long, simple and complex, is what creates the music of prose.
+
+## Literary Examples of Sound
+
+- **Kipling** (Just So Stories): Exuberant vocabulary, musical rhythms, dramatic phrasing
+- **Twain** ("Jumping Frog"): Beauty through irresistible dialectical cadences
+- **Hurston** (Their Eyes Were Watching God): Rhythm with hypnotic, fatal, forward drive — simple vocabulary whose power is all in the beat
+- **Gloss** (The Hearts of Horses): Quiet, subtle — power from the perfect placement and timing of words
+- **Woolf** (To the Lighthouse): Variety of sentence length, complex syntax including parentheses, flowing and breaking until a one-word sentence stops everything: "Awake."
+- **Twain** (Huckleberry Finn): One long sentence made of short subsentences strung by semicolons, catching the rhythm of someone talking quietly — one of the great sunrises in literature

package/payload/premium-plugins/writer-craft/references/tense-and-person.md

@@ -0,0 +1,85 @@
+# Tense and Person of the Verb
+
+## Person of the Verb
+
+### First Person (I / We)
+The narrator is a character. Everything is filtered through their perception.
+
+Historical evolution: from Cicero's letters and medieval diaries through the epistolary novel (Richardson, Austen) to the modern first-person novel. First person is often assumed to be the simplest mode, but it introduces subtle traps — especially the tendency to make every character sound alike.
+
+### Third Person (He / She / They)
+The most common and least troublesome mode. Third person ranges from extremely intimate (limited third — practically first person with different pronouns) to extremely distant (detached narrator — practically a camera).
+
+**Limited third** is restricted to the perceptions, knowledge, feelings, and memories of one character. Technically very close to first person. Switching between limited-third viewpoint characters is possible but requires awareness.
+
+### Second Person (You)
+Rare in fiction. Creates an imperative, immersive quality. Can feel gimmicky if sustained too long. Works well in short bursts or in genres where it serves a specific purpose.
+
+## Tenses of the Verb
+
+### Past Tense
+The default narrative tense throughout most of literary history. Gives continuous access to before and after — minds move around easily as they normally do.
+
+**Metaphor:** Sunlight — illuminates everything, allows the eye to roam freely across time and space.
+
+**Advantages:**
+- Natural access to memory, reflection, foreshadowing
+- Allows the narrator to know more than the character knew at the time
+- The full range of verb forms is available
+- Does not create artificial urgency
+
+### Present Tense
+Dominant in contemporary fiction for the past thirty to forty years. Narrower in field of vision — necessarily focused on action in a single time and place.
+
+**Metaphor:** A narrow-beam flashlight — intense illumination of one spot, darkness everywhere else.
+
+**Advantages:**
+- Immediacy — the reader experiences events as they unfold
+- Creates inherent urgency ("a permanent artificial emergency")
+- Can be exactly right for fast-paced action or a character whose engine runs hot
+- Prevents the narrator from reflecting at length (which can be a feature or a bug)
+
+**Dangers:**
+- Many writers use it from fashion rather than conscious choice
+- If you always write in present tense, some verb forms may atrophy
+- Sustained present tense can feel relentless — no breathing room
+- Flashbacks and memory become technically awkward
+
+### Two-Timing
+Switching between past and present tense without awareness or signal is one of the most common and disorienting errors in contemporary prose. A passage that drifts from past to present and back within a paragraph without reason is simply broken.
+
+**The rule:** Every tense shift must be deliberate and must serve the story. If switching tenses, the shift should be clear enough that the reader understands they've moved in time.
+
+### Choosing Tense
+
+Questions to ask:
+- Does the story need access to before and after? → Past tense
+- Does the story need the claustrophobic intensity of the present moment? → Present tense
+- Is the narrator looking back on events with the knowledge of what happened? → Past tense
+- Is the narrator experiencing events without foreknowledge? → Either works, but present intensifies the effect
+- Are there multiple timelines that need to be distinguished? → Tense shifts can serve this, but must be deliberate
+
+## The Passive Voice
+
+### What It Actually Is
+The passive voice reverses the normal subject-verb-object order so that the object of the action becomes the grammatical subject.
+
+- **Active:** "The dog bit the man"
+- **Passive:** "The man was bitten by the dog"
+
+### The Fake Rule
+"Never use the passive voice" is not a real rule. The passive is a legitimate construction with specific uses.
+
+### When the Passive Is Appropriate
+- When the agent is unknown: "The window was broken during the night"
+- When the agent is less important than the action or result: "The cathedral was completed in 1247"
+- When the passive creates the right rhythm: sometimes the sentence simply sounds better
+- When the passive creates emphasis: "The city was destroyed" emphasises the city; "An earthquake destroyed the city" emphasises the earthquake
+
+### When to Guard Against It
+Passive voice that seeps in from academic, bureaucratic, or business English to obscure agency and responsibility:
+- "Mistakes were made" — by whom?
+- "It was determined that..." — by whom?
+- "The decision was reached to..." — by whom?
+
+This evasive passive is worth eliminating. The useful passive is worth keeping.

package/payload/premium-plugins/writer-craft/references/transformation-framework.md

@@ -0,0 +1,86 @@
+# The Four-Stage Transformation Framework
+
+## The Template
+
+Every persuasive story moves through four stages:
+
+### Stage 1: Misbelief
+The erroneous belief your audience holds that prevents them from heeding your call to action.
+
+**How to identify it:**
+- It is not what they say their reason is — it's the emotional core beneath the surface
+- It is often a belief they are not consciously aware of holding
+- It is usually connected to identity, belonging, or self-worth
+- It was formed through experience, not logic — which is why logic can't dislodge it
+
+**Requirements:**
+- Must be specific — not "they don't care about the environment" but "they believe that environmental action requires sacrifice that marks them as different from their tribe"
+- Must be empathetically understood — you must see why this belief makes sense from inside their worldview
+- Must be something your story can actually address
+
+### Stage 2: Truth
+What the story's events will reveal as actually true. This is not your logical argument — it is the emotional reality your story will make the audience experience.
+
+**The distinction:**
+- Your logical point: what you believe the evidence shows
+- Your story's truth: what will resonate with the audience's emotional logic and uproot their misbelief
+
+These may be very different. The story's truth must be stated in terms the audience would use, not in terms you would use.
+
+### Stage 3: Realization
+The moment the protagonist (and by extension, the audience) sees the misbelief for what it is. This is the pivot of the entire story.
+
+**Four conditions for an effective realization:**
+
+1. **Timing** — Must come at the absolute last second, when all other options are exhausted and failure is imminent. Early realizations reduce stakes and satisfaction.
+
+2. **Agency** — The protagonist must make the discovery themselves. No one can hand it to them. If a mentor or saviour delivers the insight, the audience is denied the vicarious triumph.
+
+3. **Transparency** — The audience must understand why the protagonist changes their mind — not just that they do. The penny must be seen to drop. Without the "because," the realization has no instructive value.
+
+4. **Liberation** — The misbelief is shed. The protagonist is freer, more authentically themselves, capable of acting.
+
+### Stage 4: Transformation
+The protagonist is freed from the misbelief and can now act. The audience, having vicariously lived the experience, is freed too.
+
+**End at the transformation.** Do not add a coda showing the aftermath. The emotional transformation is the story's end. Everything after dilutes it.
+
+## The Point
+
+### One Story, One Point
+Every story must make exactly one point. Multiple points muddy the waters.
+
+### The Formula
+1. Changing how your audience **feels** about something...
+2. ...changes how they **see** something...
+3. ...which makes them want to **do** something
+
+### The Point Is Never Stated Outright
+Story makes its point implicitly — through what the protagonist discovers. The audience draws the conclusion themselves, which is why they believe it.
+
+### Simple vs. Simplistic
+- **Simple** has layers beneath an elegant surface: "Just Do It." "We'll leave the light on."
+- **Simplistic** has no depth: "Be Your Way." "Enjoy Better." "Pork, Be Inspired."
+
+Simple works because it taps into a complex internal narrative the audience already holds. Simplistic doesn't tap into anything.
+
+### The Target Emotion
+The emotion must be specific and fused to the point. Generic fear leads to paralysis or denial. The goal: trigger the specific emotion that reveals why your call to action matters — and then the relief of seeing how to resolve it.
+
+## Story Construction
+
+### Basic Template
+- One protagonist (representing your audience)
+- One specific external problem (not generic — today's problem)
+- Three escalating twists, each raising stakes
+- One "aha" moment meeting all four conditions
+- One ending at the transformation
+
+### The Rule of Threes
+The brain looks for patterns, and the minimum viable pattern is three. Three twists create a satisfying arc: two failed attempts, then the breakthrough. Each must be distinct and must escalate.
+
+### Believability at Two Levels
+1. **Physical** — Does this make physical sense?
+2. **Psychological/emotional** — Does this make sense given who the protagonist is and how their tribe sees the world?
+
+The emotional level is the only one that truly matters. A talking baby (E*TRADE) violates physical believability — but works perfectly because it captures the emotional logic of its target audience.

package/payload/premium-plugins/writer-craft/references/word-economy.md

@@ -0,0 +1,93 @@
+# Word Economy: Adjectives, Adverbs, Crowding, and Leaping — Steering the Craft
+
+## Adjectives and Adverbs
+
+Adjectives and adverbs are rich, good, and nourishing. They add colour, life, immediacy. They cause obesity in prose only when used lazily or overused.
+
+### The Core Principle
+When the quality an adverb indicates can be put directly in the verb, or when the quality an adjective indicates can be put in the noun itself, the prose will be cleaner, more intense, more vivid.
+
+| Weak | Strong |
+|------|--------|
+| They ran quickly | They raced / They sprinted |
+| A growling voice | A growl |
+| She said loudly | She shouted / She bellowed |
+| He walked slowly | He shuffled / He crept |
+| A big house | A mansion / A sprawl |
+
+### Bloodsuckers: Qualifiers
+These words weaken almost every sentence they appear in:
+- rather
+- a little
+- just
+- very
+- kind of / sort of
+- somewhat
+- quite
+- really
+- perhaps (when hedging, not when genuinely uncertain)
+
+They are ticks in written prose. In conversation, they serve as social lubricant. In prose, they drain authority and precision.
+
+### Empty Intensifiers
+Words that have lost their meaning through overuse:
+- great
+- suddenly
+- somehow
+- absolutely
+- totally
+- literally (when used as emphasis)
+- amazing / incredible / unbelievable
+
+### The Muscle-to-Fat Ratio
+Narrative prose, especially long narrative, needs more muscle than fat. The English language is rich beyond belief — but richness must be earned by precision, not accumulated through decoration.
+
+## Crowding
+
+**Crowding** means loading every rift with ore. Avoiding flabby language and clichés. Always seeking the vivid phrase. Keeping the story full of what's happening in it, keeping it moving, keeping it interconnected.
+
+### Qualities of Crowded Prose
+- **Vivid** — the reader can see, hear, feel what's happening
+- **Exact** — the right word, not its approximate cousin
+- **Concrete** — specific objects, actions, sensations — not abstractions
+- **Accurate** — true to the physical and emotional reality being described
+- **Dense** — every sentence carrying weight
+- **Rich** — multiple layers of meaning working simultaneously
+
+### How to Crowd
+- Seek the specific over the general
+- Choose the vivid verb over the weak verb + adverb
+- Choose the precise noun over the generic noun + adjective
+- Make every detail do double or triple duty (reveal character AND advance plot AND illuminate theme)
+- Eliminate any word that isn't pulling its weight
+
+## Leaping
+
+**Leaping** means what you leave out. What you leave out is infinitely more than what you leave in. There must be white space around the word, silence around the voice.
+
+### What to Leave Out
+- Information the reader can infer
+- Steps in a sequence that are obvious
+- Descriptions of what the reader already knows or can imagine
+- Transitions that don't need to be spelled out
+- Emotional states that are already clear from action and dialogue
+
+### Listing Is Not Describing
+A catalogue of objects or actions does not create a vivid scene. Only the details that matter — that carry meaning — belong. The rest is noise.
+
+### The Danger of Overcrowding
+Even good writers can overdo crowding. Borges's fictional character Funes the Memorious perceived and remembered every detail of everything — and was utterly paralysed by it. Flaubert's Salammbô is a real-world cautionary tale: a novel choked by its own mots justes.
+
+### The Danger of Insufficient Leaping
+Action writing that tries to give blow-by-blow accounts creates confusion and boredom. The reader doesn't need to see every swing of the sword. They need to see the moments that change the stakes.
+
+## The Revision Method
+
+Crowd in the first draft — be generous, overwrite, include too much. Then cut.
+
+**Decide what counts, what tells, and cut and recombine until what's left is what counts.**
+
+Chekhov's advice: "First, throw out the first three pages." Most first drafts circle and explain before they find their way. In revision, if the beginning can be cut, cut it.
+
+### The Halving Exercise
+Take a piece of 400+ words and cut it to half — not trimming but counting words and actually reducing to half while keeping the narrative clear and the sensory impact vivid. This forces you to discover which words are Styrofoam and which are heavy gold.

package/payload/premium-plugins/writer-craft/skills/citation-style.md

@@ -0,0 +1,94 @@
+---
+name: citation-style
+description: "Guides Chicago author-date citation and reference formatting per the Chicago Manual of Style (17th edition). Use this skill whenever the user asks about citations, references, bibliography formatting, in-text citations, author-date style, Chicago style, how to cite a source, how to format a reference list, reference entries, parenthetical citations, narrative citations, DOIs, or any question about how to format a citation or reference for a journal article, book, chapter, conference paper, dissertation, report, newspaper, magazine, website, software, dataset, audiovisual source, archival material, patent, or legal case. Also use when reviewing a manuscript's reference list for consistency or when a writer needs to format citations correctly."
+---
+
+# Citation Style: Chicago Author-Date
+
+This skill covers citation and reference formatting in accordance with the Chicago Manual of Style, Seventeenth Edition (2017), using the author-date system. This is the standard for many academic journals and publishers.
+
+## In-Text Citations
+
+Citations appear in two forms:
+
+### Narrative Citations
+The author surname(s) appear as part of the sentence. The year follows in parentheses.
+- `According to Singh and Harris (2018), this phenomenon occurs frequently.`
+- `In 2018, Singh and Harris reported on the frequency...`
+
+### Parenthetical Citations
+The author surname(s) and year appear together in parentheses, placed at the end of a sentence before terminal punctuation.
+- `This phenomenon occurs frequently in nature (Singh and Harris 2018).`
+
+### Author Rules in Citations
+
+| Authors | Citation Form |
+|---------|-------------|
+| 1 | Surname (Year) |
+| 2 | Surname and Surname (Year) |
+| 3 | Surname, Surname, and Surname (Year) |
+| 4+ | Surname et al. (Year) |
+| Organizational | Full name or abbreviation if reference uses one |
+| No author | Short title in title case (Year) |
+
+### Page Numbers with Quoted Passages
+A comma separates year from page number: `(Liu et al. 2009, 124)` or for a range: `(Liu et al. 2009, 124–125)`.
+
+### Multiple Citations
+Arrange alphabetically by author surname; separate with semicolons: `(Abbas and Ludden 2018; Carlyle 1997; Carlyle et al. 1997)`
+
+### Same Author, Same Year
+Add lowercase letter designators: `(Murakami 2003a, 2003b)`
+
+### Secondary Sources
+Use "quoted in": `(Huang and Zoller 1995, quoted in Zhu 2010, 18)`
+
+## Reference List
+
+The reference section appears at the end of the text under the heading "References." It includes entries for all works cited. Entries use hanging indent format.
+
+### Ordering Rules
+1. Alphabetical by first author's surname
+2. Same first author → alphabetical by subsequent authors
+3. Same full author list → chronological by publication date
+4. Same authors and year → alphabetical by title, with letter designators (a, b, c)
+5. Organizational authors ordered alphabetically by name/acronym
+6. No credited author → alphabetical by title among other entries
+
+### Author Formatting in References
+- First author: Surname, Given Name(s) or Initial(s).
+- Subsequent authors: Given Name(s) Surname (not inverted)
+- 2–10 authors: list all, "and" before final name
+- 11+ authors: list first seven, then "et al."
+- Do not replace repeated names with dashes
+
+### Titles
+- Journal/magazine/newspaper titles: italicised, title case, no quotation marks
+- Article/chapter titles: roman font, quotation marks, title case
+- Book/report titles: italicised, title case
+
+### URLs and DOIs
+- DOIs close journal article entries (when available)
+- URLs close web and other electronic resource entries
+- Access dates recorded only when no publication date can be determined
+
+## Quick Formatting Checklist
+
+- [ ] All in-text citations have corresponding reference entries (and vice versa)
+- [ ] Author names formatted correctly (inverted first author, non-inverted subsequent)
+- [ ] 4+ authors use "et al." in citations, full list (up to 10) in references
+- [ ] Publication years present on all entries (or "n.d." / "forthcoming")
+- [ ] Journal articles include volume, issue number, page range, and DOI
+- [ ] Book entries include city and publisher
+- [ ] Titles use correct capitalisation and formatting (italic vs. quotation marks)
+- [ ] Reference list alphabetised correctly
+- [ ] Same-author/same-year entries have letter designators
+- [ ] Hanging indent format throughout reference list
+
+## When to Read Reference Files
+
+- **For detailed in-text citation rules** (placement, authors, years, special cases) — read `references/citation-rules.md`
+- **For general reference list formatting rules** (ordering, author lists, titles, URLs/DOIs) — read `references/reference-list-rules.md`
+- **For journal article reference models** with examples — read `references/journal-article-models.md`
+- **For book and book chapter reference models** with examples — read `references/book-and-chapter-models.md`
+- **For all other source types** (conferences, dissertations, reports, newspapers, magazines, web, software, audiovisual, unpublished, archival, legal) — read `references/other-source-models.md`