DOCS/TRD.md

# Technical Requirements Document (TRD)

## Greige Issuance Decision Intelligence CRM

**Prepared by:** Ascentia Labs
**Client Name:** Vardhman Textiles
**Date:** 11th March, 2026
**Version:** 1.0
**Subject:** To classify technical requirements into Locked requirements & Ad Hoc requirements that may be part of the solution development journey

---

## 1. Executive Overview

### 1.1 Product Vision

The **Greige Issuance Decision Intelligence CRM** is a complete intelligent system that transforms how Vardhman Textiles plans fabric production.

The system combines three integrated capabilities into one cohesive platform:

**Intelligence Analysis:** Learns from every order ever processed to understand what works. Analyzes historical performance patterns across articles, routes, finishes, and customer segments. Identifies optimal fabric reservation percentages based on actual outcomes rather than static rules.

**Operational Management:** Organizes all master data (Articles, Customers, Planning Rules) and transactional workflows (Sale Orders and Production Orders) in one place. Surfaces complete historical performance for every article and order. Manages versioned planning rules with full audit trails.

**Action Guidance:** Suggests specific improvements based on intelligence analysis. Creates a structured cycle from insight to action to resolution to impact measurement. Tracks which suggestions were implemented and measures their effectiveness.

This unified platform replaces fragmented Excel-based planning and ad-hoc decision-making with a governed, data-driven workflow—making it the single source of truth for greige issuance planning at Vardhman Textiles.

---

### 1.2 The Core Business Problem

Vardhman Textiles processes thousands of greige (unfinished) fabric orders annually. The critical planning decision is: **how much raw fabric to issue for each production order.**

- **Over-issuing** → Wastes expensive cotton/Tencel, creates deadstock
- **Under-issuing** → Causes shortfalls, requires costly reprocessing

Traditional planning uses static norms — e.g., "always add 5% buffer" — which ignore article-specific behavior, historical performance, and manufacturing variation. Different articles, routes, and finishes behave very differently; a uniform rule serves none of them well.

**The system answers:** *"Based on what actually worked for this specific article type historically, here is the precise reservation percentage you need — and here is why."*

---

### 1.3 System Capabilities

The system delivers comprehensive capabilities across intelligence, operations, and actions:

| Capability                          | Description                                                                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Data Integration**          | Ingests sale order data (Excel or NOW system), classifies 46 PO types (Fresh vs. Reprocess), aggregates to order-line level with deduplication   |
| **Core Quantity Metrics**     | Order Qty, Reserved Qty, Issued Qty, Pack Fresh, Total Packing, Reprocess Qty — per PO, per order, per article                                  |
| **Percentage KPIs**           | Extra Gr Reserved %, Actual Gr Issue %, Shrinkage %, Fresh Pkg %, Fresh to Order %, Fresh Yield %                                                |
| **Waterfall Analysis**        | Quantity flow breakdown: Demand → Policy Gap → Execution Adjustment → Process Loss → Delivered                                               |
| **Blame Attribution**         | Apportions responsibility for shortfalls/waste across Policy (norms), Execution (planner decisions), and Process (manufacturing)                 |
| **Decision Intelligence**     | Norm Adequacy, Intervention ROI, False Yield Warning, Safety Recommendation, Elasticity classification, Risk Fingerprint, PO Imbalance Detection |
| **AI Recommendation Engine**  | Article-level reservation % recommendations based on historical performance analysis, with confidence levels and plain-English explanations      |
| **Planning Rules Management** | Rule-based lookup against 46+ norm rules using division factor, sub-type, composition, and count range                                           |
| **CRM Modules**               | Complete management of Articles, Customers, Sale Orders, Norms (versioned), and Actions                                                          |
| **Executive Reporting**       | Global KPIs, article performance, route analysis, customer segments, planner execution, norms effectiveness                                      |

**System Coverage:** 4,613 PO rows · 970 unique sale orders · 496 unique articles · all formulas validated against Excel

---

## 2. Product Architecture

### 2.1 How the System Works (Business View)

The system follows a continuous learning cycle for every production order:

```
┌─────────────────────┐
│   ORDER ENTRY       │ → Order details entered (article, quantity, customer)
└──────────┬──────────┘
           ↓
┌─────────────────────────┐
│ INTELLIGENCE ANALYSIS   │ → System analyzes similar past orders
└──────────┬──────────────┘   Identifies patterns in success/failure
           ↓
┌──────────────────────────┐
│  AI RECOMMENDATION       │ → Suggests optimal fabric buffer %
└──────────┬───────────────┘   Explains why based on history
           ↓
┌─────────────────────┐
│  PLANNER DECISION   │ → Planner reviews and confirms
└──────────┬──────────┘   System tracks outcome
           ↓
┌─────────────────────┐
│ OUTCOME LEARNING    │ → After order completes, AI improves
└─────────────────────┘   Better recommendations for next time
```

### 2.2 The Three Core Capabilities

#### The Brain (Intelligence Engine)

**Purpose:** Learns from history to make data-driven recommendations

**What It Does:**

- Analyzes every order processed historically to identify patterns
- Understands which articles consistently succeed or fail
- Learns which fabric buffer percentages work for different article types
- Detects when performance patterns change over time
- Generates article-specific recommendations with confidence levels

**Business Value:** Replaces guesswork with evidence-based planning

---

#### The Organizer (CRM & Data Management)

**Purpose:** Single source of truth for all planning data

**What It Does:**

- Stores all articles with complete construction details and performance history
- Manages customer information and segment-level analysis
- Tracks every sale order with full production order breakdown
- Maintains versioned planning rules with change history
- Provides searchable, filterable access to all historical data

**Business Value:** Eliminates fragmented Excel files, ensures data consistency

---

#### The Advisor (Action Center)

**Purpose:** Turns insights into measurable improvements

**What It Does:**

- Surfaces contextual action suggestions on every screen
- Creates structured action items (Norm Revision, Order Review, Process Investigation)
- Assigns actions to planners or managers with tracking
- Measures impact: Did acting on this suggestion improve results?
- Provides action analytics: open vs. resolved, by type, by assignee

**Business Value:** Closes the loop from analysis to action to improvement

---

### 2.3 Following an Order Through the System

**Example: New Order for Article 18006BA (Cotton 40s Soft Continuous)**

**Step 1: Order Creation**

- Planner creates sale order: 10,000 meters
- System identifies article: 18006BA
- Route: Continuous, Finish: Soft, Shade: Dyed

**Step 2: Intelligence Analysis**

- System retrieves 87 historical orders for this article
- 74 orders succeeded (Pack Fresh ≥ Order Qty)
- 13 orders had shortfalls
- Analyzes typical successful buffer percentages

**Step 3: AI Recommendation**

- System recommends: 5.2% reservation buffer
- Current planning rule: 6.0%
- Confidence: HIGH (87 historical orders)
- Explanation: "93% of orders fulfilled at 5.2% buffer; current norm 6.0% may be excessive"

**Step 4: Planner Decision**

- Planner reviews recommendation and comparison
- Decides to use 5.5% (between AI and norm)
- Issues 10,550 meters to production
- System records decision for future learning

**Step 5: Production & Outcome**

- Manufacturing processes the fabric
- Final Pack Fresh: 10,120 meters
- Fresh Yield: 95.9% (excellent)
- Result: Order fulfilled successfully

**Step 6: Learning**

- System records outcome as success
- Updates article performance history
- Future recommendations for this article incorporate this result
- If planner's adjustment helped, system learns from the intervention

---

### 2.4 How the System Learns

#### Learning from Historical Patterns

The system treats every completed order as a learning example:

**Pattern Analysis:**

- Retrieves all historical orders for the same article type
- Classifies each order: Success (fulfilled) or Failure (shortfall)
- Identifies which buffer percentages consistently led to success
- Filters exceptional cases (lucky successes or wasteful over-issues)
- Focuses on typical patterns that work regularly

**Example:**

```
Article: Cotton 40s Soft Continuous
Historical Orders: 87
Successful: 74 orders (85% success rate)
Typical successful buffer: 4.8% to 5.6%
Recommendation: 5.2% (median of typical range)
```

---

#### Continuous Improvement

The system updates its understanding after every order completes:

**Recent Weighting:**

- More recent orders have greater influence on recommendations
- Older orders still contribute but with reduced weight
- Balances historical patterns with current conditions

**Drift Detection:**

- Monitors when article behavior changes over time
- Example: If an article's yield drops from 95% to 88% consistently
- System detects pattern shift and adjusts recommendations accordingly

**Adaptation Cycle:**

```
Order Completes → Outcome Recorded → Pattern Analysis Updated → 
Confidence Recalculated → Recommendations Refined → Applied to Next Order
```

---

#### Knowledge Transfer for New Articles

For articles with limited or no history, the system leverages similarity:

**Similarity Matching:**

- Identifies articles with similar characteristics:
  - **Composition:** Cotton, PC, Viscose, Modal (exact match preferred)
  - **Processing Route:** Continuous, Jet, Jigger, Winch
  - **Finish Type:** Soft, Peach, Normal, etc.
  - **Yarn Count:** 40s, 60s, etc.
  - **Order Size Patterns:** Small, medium, large orders

**Transfer Learning:**

- Finds 5-10 most similar articles with strong historical data
- Transfers successful patterns from these articles
- Generates initial recommendation with LOW confidence
- Refines recommendation as direct history accumulates

**Example:**

```
New Article: Cotton Stretch 40s Soft Continuous
Similar Articles Found: 12
- Cotton 40s Soft Continuous (87 orders, 85% success)
- Cotton Stretch 60s Soft Continuous (34 orders, 79% success)
- Cotton 40s Peach Continuous (56 orders, 82% success)

Initial Recommendation: 5.4% (averaged from similar articles)
Confidence: LOW (no direct history)
Note: "Based on 12 similar articles with 177 total orders"
```

---

#### Confidence Tracking

The system provides transparency about recommendation reliability:

| Confidence Level      | Criteria                                       | Interpretation                           |
| --------------------- | ---------------------------------------------- | ---------------------------------------- |
| **HIGH**        | 50+ historical orders with consistent patterns | Strong evidence, reliable recommendation |
| **MEDIUM**      | 10-49 orders with moderate consistency         | Good evidence, reasonable confidence     |
| **LOW**         | 5-9 orders or inconsistent patterns            | Limited evidence, use caution            |
| **NEW ARTICLE** | <5 orders, using similarity matching           | Preliminary guidance, monitor closely    |

**Confidence Display:**

```
Recommendation: 5.2% buffer
Confidence: HIGH
Supporting Data: 87 historical orders analyzed
Success Rate: 85% (74 of 87 orders fulfilled)
Pattern Consistency: Strong (typical range 4.8%-5.6%)
```

---

#### Decision Optimization

The system optimizes recommendations for multiple objectives:

**Priority 1: Fulfill Customer Orders**

- Primary goal: Avoid shortfalls
- System strongly prioritizes meeting Order Qty
- Recommendation ensures high probability of fulfillment

**Priority 2: Minimize Fabric Waste**

- Secondary goal: Avoid excess issuance
- Balances safety margin against material cost
- Aims for "just enough" buffer

**Priority 3: Reduce Reprocessing**

- Tertiary goal: Get it right the first time
- Reprocessing is costly and time-consuming
- Recommendations consider reprocessing history

**Optimization Balance:**

- If article has high shortfall history: System adds safety margin
- If article consistently over-delivers: System reduces buffer
- If article has quality issues: System flags for investigation, not just higher buffer

---

## 3. Technical Architecture

### 3.1 System Architecture

```
┌───────────────────────────────────────────────────────────────┐
│                    WEB APPLICATION                            │
│              What planners and managers see                   │
│                                                               │
│    Articles  │  Customers  │  Sale Orders  │  Norms  │  Reports│
│    ─────────────────────────────────────────────────────────  │
│    Action Planning (Inline per screen + Standalone Center)    │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            ↓
┌───────────────────────────────────────────────────────────────┐
│            INTELLIGENCE & DATA LAYER                          │
│                                                               │
│  • Analyzes performance patterns across all historical data   │
│  • Generates AI recommendations with confidence levels        │
│  • Stores all articles, customers, orders, and planning rules │
│  • Calculates metrics, waterfall, blame attribution, KPIs     │
│  • Manages versioned norms with change tracking               │
└───────────────────────────┬───────────────────────────────────┘
                            │
                            ↓
┌───────────────────────────────────────────────────────────────┐
│                    DATA SOURCES                               │
│                                                               │
│  • Excel file upload/download (manual operations)             │
│  • NOW system integration (automated sync)                    │
│  • Historical production data (4,613 PO records)              │
│  • Versioned planning rules database (46+ norm rules)         │
└───────────────────────────────────────────────────────────────┘
```

### 3.2 Technology Stack

| Layer                     | Technology                 | Why We Use It                                                |
| ------------------------- | -------------------------- | ------------------------------------------------------------ |
| **Frontend**        | Next.js 14 (App Router)    | Fast, modern user interface with server-side rendering       |
| **Styling**         | Tailwind CSS               | Consistent, professional appearance across all screens       |
| **UI Components**   | shadcn/ui + Radix          | Accessible, enterprise-grade component library               |
| **Charts**          | Recharts                   | Interactive data visualization for dashboards                |
| **Backend**         | FastAPI (Python)           | High-performance API for complex calculations                |
| **Data Processing** | Pandas                     | Efficient handling of large datasets with complex operations |
| **Database**        | PostgreSQL                 | Reliable, scalable data storage with ACID compliance         |
| **ORM**             | SQLAlchemy / Prisma        | Database abstraction for maintainable data layer             |
| **Authentication**  | Role-based access control  | Secure user permissions (Planner / Manager / Admin)          |
| **Data Input**      | Excel (openpyxl) + NOW API | Dual ingestion mode for flexibility and integration          |

### 3.3 Data Integration

The application supports two distinct phases for data ingestion, progressing from manual operations to automated integration:

#### Phase 1: Manual Data Ingestion

| Aspect               | Description                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| **Method**     | Excel file upload and download                                             |
| **Use Case**   | Standalone use, ad-hoc analysis, initial setup, backup fallback            |
| **Operations** | Manual file upload → System processes → Results displayed and exportable |

In Phase 1, planners manually upload Excel files containing sale order and production order data. The system processes the data and provides results that can be exported back to Excel for further analysis. This phase is ideal for initial deployment, testing, and scenarios where real-time integration is not available.

#### Phase 2: Automated Data Ingestion

| Aspect               | Description                                                                    |
| -------------------- | ------------------------------------------------------------------------------ |
| **Method**     | Direct API integration with Vardhman's NOW system                              |
| **Use Case**   | Real-time automated sync, primary production mode                              |
| **Operations** | System polls NOW API → Auto-imports new orders → Real-time dashboard updates |

Phase 2 enables seamless, automated data synchronization with Vardhman's existing NOW enterprise system. The system automatically polls for new orders, imports them in real-time, and updates all dashboards and analytics without manual intervention. This is the primary mode for production operations.

**Progression:**

- Phase 1 serves as the foundation and fallback mechanism
- Phase 2 is deployed once NOW API integration is configured
- Both phases can coexist — Phase 1 available as backup when needed

---

## 4. Intelligence Capabilities

### 4.1 Key Performance Metrics

All metrics are computed per PO, per sale order, and aggregated per article/route/segment.

| Metric                        | Formula                                    | Business Meaning                              |
| ----------------------------- | ------------------------------------------ | --------------------------------------------- |
| **Extra Gr Reserved %** | (Reserved − Order Qty) / Order Qty × 100 | Buffer added by norms                         |
| **Actual Gr Issue %**   | (Issued − Order Qty) / Order Qty × 100   | Buffer actually issued by planner             |
| **Shrinkage %**         | (Issued − Total Packing) / Issued × 100  | Manufacturing loss (defects, shrinkage, trim) |
| **Fresh Pkg %**         | Pack Fresh / Total Packing × 100          | First-run quality rate                        |
| **Fresh to Order %**    | Pack Fresh / Order Qty × 100              | Fulfillment rate — ≥100% = no shortfall     |
| **Fresh Yield %**       | Pack Fresh / Fresh Issued × 100           | Production efficiency — the primary AI input |
| **Shortfall**           | Order Qty − Pack Fresh (when positive)    | Unfulfilled quantity requiring reprocessing   |

**Typical Benchmark Ranges:**

- Shrinkage: 3–5% normal, >7% indicates quality issues
- Fresh Yield: >95% excellent, 90–95% good, <85% poor
- Fresh Pkg: >95% excellent, <85% significant issues

### 4.2 Waterfall Analysis

The waterfall breaks down the complete quantity journey from customer demand to final delivery, making every stage of loss or gain visible:

```
Demand (Order Qty)               ← What customer ordered
    ↓  + Policy Gap              ← Buffer added by norms (Reserved − Order Qty)
Reserved Qty                     ← What norms said to issue
    ↓  + Execution Adjustment    ← Planner's deviation from norms (Issued − Reserved)
Issued Qty                       ← What was actually sent to production
    ↓  + Process Loss            ← Manufacturing losses (Pack Fresh − Issued)
Delivered (Pack Fresh)           ← Final first-run quality output

Validation: Demand + Policy Gap + Execution Adj + Process Loss = Delivered ✓
```

### 4.3 Blame Attribution

For any order with a variance (shortfall or excess issuance), the system quantifies which factor is most responsible:

- **Policy %** — How much of the variance came from norm rules being inadequate or excessive
- **Execution %** — How much came from the planner deviating from norms
- **Process %** — How much came from manufacturing losses (shrinkage, defects)

Each is calculated as a share of total absolute variance, displayed as a stacked bar. This converts post-mortem analysis from guesswork into quantified accountability.

### 4.4 Decision Intelligence Metrics

Beyond raw metrics, the engine computes higher-order intelligence per order:

| Metric                           | What It Tells You                                                                          |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| **Norm Adequacy**          | Were the norms sufficient for this order? (Pack Fresh / Order Qty)                         |
| **Intervention ROI**       | Was the planner's deviation from norms beneficial, neutral, or harmful?                    |
| **False Yield Warning**    | High yield % but still a shortfall — a planning failure masked by efficient manufacturing |
| **Safety Recommendation**  | What reservation % should be used for future similar orders, based on actual yield         |
| **Breakeven Tolerance**    | How much shrinkage buffer did the planner have before a shortfall would occur              |
| **Elasticity**             | Yield stability classification: HIGH (≥90%), MEDIUM (80–90%), LOW (<80%)                 |
| **Risk Fingerprint**       | Composite risk profile: norm reliability, reprocessing dependence, risk level              |
| **PO Imbalance Detection** | Inconsistent reservation % across POs in the same order — signals ad-hoc planning         |

### 4.5 AI Recommendation Engine

For each article, the system generates a recommended reservation percentage based on historical performance analysis.

#### How Recommendations are Generated

**Analysis Process:**

1. **Identify Planning Rule:** Match article to its applicable norm via division factor, sub-type, composition, and count range
2. **Retrieve Historical Orders:** Pull all past orders for this specific article type from the database
3. **Classify Order Outcomes:**

   - Success: Pack Fresh ≥ Order Qty (order fulfilled)
   - Failure: Pack Fresh < Order Qty (shortfall occurred)
4. **Analyze Successful Orders:** Focus on what worked — examine buffer percentages used in successful orders
5. **Filter Extreme Cases:** Remove outliers that represent lucky successes (very low buffer) or wasteful over-issues (very high buffer). Keep the typical middle range of successful orders.
6. **Calculate Optimal Buffer:** Determine the buffer percentage that consistently works for this article type
7. **Add Safety Margin:** Apply appropriate safety adjustment based on performance variability and risk factors
8. **Generate Confidence Level:** Assess reliability based on:

   - Number of historical orders available
   - Consistency of performance patterns
   - Recency of data
9. **Create Explanation:** Generate plain-English reasoning showing why this recommendation makes sense

#### Confidence Levels

| Level                 | Criteria                                               | Meaning                                        |
| --------------------- | ------------------------------------------------------ | ---------------------------------------------- |
| **HIGH**        | 50+ historical orders with consistent success patterns | Strong evidence, reliable recommendation       |
| **MEDIUM**      | 10-49 historical orders with moderate consistency      | Good evidence, reasonable confidence           |
| **LOW**         | 5-9 historical orders or inconsistent patterns         | Limited evidence, use with caution             |
| **NEW ARTICLE** | <5 orders, using similarity to other articles          | Preliminary guidance based on similar articles |

#### Recommendation Output

Each recommendation provides:

**Primary Recommendation:**

- Optimal reservation percentage (e.g., 5.2%)
- Expected outcome if followed (e.g., "95% probability of fulfillment")

**Comparison:**

- Current planning rule percentage (e.g., 6.0%)
- Difference and potential improvement (e.g., "0.8% reduction in buffer = 90m savings per order")

**Supporting Evidence:**

- Number of orders analyzed (e.g., "Based on 87 historical orders")
- Success rate (e.g., "74 of 87 orders (85%) succeeded")
- Typical range (e.g., "Successful orders used 4.8%-5.6% buffer")

**Explanation:**

- Plain-English reasoning: "93% of historical orders for this article fulfilled successfully at 5.2% buffer. Current norm of 6.0% may be excessive, leading to material waste."

**Confidence Indicator:**

- HIGH / MEDIUM / LOW with supporting data count

#### Special Cases

**No Successful Orders:**
If an article has no successful historical orders:

- System examines failed orders
- Recommends: Highest failed reservation % + 2% robust safety buffer
- Flags article for process quality investigation
- Confidence: LOW with warning

**New Articles (No Direct History):**

- System finds 5-10 similar articles by composition, route, finish
- Transfers patterns from similar successful articles
- Initial recommendation with LOW confidence
- Updates as direct history accumulates

---

## 5. CRM Modules — Functional Requirements

### 5.1 Article Management

Articles are the central master data entity. An article is a unique fabric definition identified by its construction, yarn count, and product type (e.g., "18006BA — 100% Cotton 40s Soft Continuous").

#### Article Catalog

- Full searchable, filterable list of all 496+ articles
- Filter by: composition, count range, route, finish type, shade type, risk level
- Quick-view columns: article code, product type, avg Fresh Yield %, success rate, current norm version

#### Article Profile (Detail Page)

Each article opens to a dedicated profile showing the complete picture:

- **Attributes panel:** composition, count, route, finish, shade type, product group, linked norm version ID
- **Historical performance summary:** total orders, avg yield %, shortfall rate %, avg buffer % used, avg shrinkage %
- **All historical orders table:** filterable list of every sale order for this article with outcome
- **Aggregated Waterfall chart:** policy/execution/process breakdown across all orders for this article
- **Blame Attribution chart:** where does this article's variance typically originate?
- **AI Prediction panel:** recommended reservation % with confidence level, historical analysis narrative, comparison to current norm
- **Elasticity & Risk:** stability classification and risk fingerprint

#### Inline Action Suggestions

Contextual prompts surfaced from the intelligence engine, e.g.:

- *"Norms excessive: AI recommends 5.2% vs. current norm 6.0%. Consider norm revision — 93% of orders fulfill at lower buffer."*
- *"High reprocessing dependence (18% of delivery from reprocess). Investigate process quality."*

---

### 5.2 Customer Management

#### Customer Directory

- Master list of all customers with profile data: name, segment (Domestic / Export), linked sale orders
- Segment-level summary KPIs for Domestic vs. Export cohorts

#### Customer Profile (Detail Page)

- All sale orders placed by this customer
- Aggregate fulfillment metrics: total ordered, total fulfilled, shortfall rate, avg fresh yield
- Segment benchmarking: how does this customer compare to segment average
- Trend: fulfillment rate over time

#### Inline Action Suggestions

Example prompts:

- *"This customer's orders show 22% shortfall rate vs. segment average of 8%. Review article selection and norms coverage."*

---

### 5.3 Sale Order Management

Sale Orders are the primary transactional entity. Each Sale Order (COPS_NO) contains one or more order lines, each fulfilled through one or more Production Orders.

#### 5.3.1 Sale Order List

- Searchable, filterable, sortable list of all sale orders
- Status badges: **Fulfilled** / **Shortfall** / **Reprocess Required** / **In Progress**
- Inline metrics: Order Qty, Issued Qty, Pack Fresh, Fresh to Order %, Shortfall amount
- Filters: article, customer, date range, route, status, segment, norm version

#### 5.3.2 Sale Order Detail

Each order opens to a full detail view with the complete intelligence output:

**Header:** Order number (COPS_NO), customer name, article, date, order quantity, fulfillment status

**Quantity Panel (absolute metrics):**

- Order Qty, Reserved Qty (per norms), Issued Qty (actual), Pack Fresh, Total Packing, Reprocess Qty
- Shortfall or Surplus quantity

**Performance Panel (percentage KPIs):**

- Extra Gr Reserved %, Actual Gr Issue %, Shrinkage %, Fresh Pkg %, Fresh to Order %, Fresh Yield %

**Waterfall Chart:** Visual step-down from Demand through Policy Gap, Execution Adjustment, Process Loss to Delivered — with values at each step

**Blame Attribution Chart:** Stacked bar — Policy % / Execution % / Process % — with color coding (Amber / Blue / Red) and interpretation text

**Decision Intelligence Panel:**

- Norm Adequacy with pass/fail indicator
- Intervention ROI status (High / Low / Negative / Neutral) with narrative
- False Yield Warning alert (if high yield but shortfall present)
- Safety Recommendation: optimal reservation % for future orders of this article, with confidence range
- Breakeven Tolerance: how much buffer margin the planner had
- Risk Fingerprint: norm reliability score, reprocessing dependence %, risk level
- PO Imbalance flag: if buffer % varies inconsistently across POs in this order

**Norms Reference:** The specific norms version ID that was active when this order was created — with a link to view that version's rules in read-only mode

**Inline Action Suggestions** derived from this order's metrics

#### 5.3.3 Production Order (PO) Sub-Order Breakdown

Each Sale Order contains a full breakdown of its Production Orders:

| Column         | Description                                            |
| -------------- | ------------------------------------------------------ |
| PO Number      | Production order identifier                            |
| PO Type        | Fresh Input / Reprocess / Shortfall Correction / Other |
| PO Qty         | Planned quantity for this PO                           |
| Reserved Qty   | Norm-based reserved quantity                           |
| Issued Qty     | Actual issued quantity                                 |
| Pack Fresh     | First-run packed quantity                              |
| Total Pack Qty | All packed quantity                                    |
| Yield %        | Pack Fresh / Issued × 100                             |
| Deviation %    | (Issued − Reserved) / Reserved × 100                 |

Fresh vs. Reprocess POs are visually distinguished. Reprocess POs are clearly labeled as corrective actions and excluded from primary performance metrics. PO Imbalance alert shown if buffer % varies significantly across Fresh POs in the same order.

---

### 5.4 Report Dashboards

A dedicated reporting module with configurable views for planners and managers.

#### 5.4.1 Global KPI Dashboard

- Fleet-wide: total order volume, total issued, total pack fresh, total shortfall, total reprocess volume
- Fresh Yield %, Shrinkage %, Shortfall Rate %, Reprocess Rate % — current period and trend
- Month-over-month and quarter-over-quarter trend lines for all major KPIs

#### 5.4.2 Article Performance Dashboard

- Articles ranked by yield, shortfall rate, excess issuance, reprocess frequency
- AI improvement opportunity: articles where norms are consistently excessive or insufficient
- Scatter: Reservation % vs. Fresh Yield % per article — identify outliers

#### 5.4.3 Route / Process Dashboard

- Performance breakdown by Route: Continuous, Jet, Jigger, Winch
- Shrinkage %, Fresh Yield %, Reprocess Rate % per route
- Blame Attribution aggregated by route — which routes have the most Process-attributed losses

#### 5.4.4 Customer / Segment Dashboard

- Fulfillment rates by customer and by segment (Domestic vs. Export)
- Shortfall and reprocess volumes per customer — trend view
- Cross-segment benchmarking

#### 5.4.5 Planner Execution Dashboard

- Distribution of Execution Adjustment (planner deviation from norms) over time
- Intervention ROI breakdown: how often do planner overrides help vs. hurt?
- Orders where Execution was the dominant blame factor

#### 5.4.6 Norms Effectiveness Dashboard

- Norm Adequacy rate across all orders
- Articles where AI recommendation consistently diverges from current norm — shortlist of revision candidates
- Projected impact simulation: if AI-recommended buffers were applied fleet-wide, estimated reduction in shortfalls and excess issuance

All dashboards support Excel export for offline review.

---

### 5.5 Norms Management

Norms are the rule set that defines how much greige buffer to reserve for each article category. Currently maintained as a static file (norms.json, Rev 68, effective 13-12-2025, 46+ rules). The CRM digitalizes norms into a governed, versioned system.

#### 5.5.1 Norms Registry

Structured, searchable table of all active norm rules:

- Division Factor (Continuous / Jet / Jigger / Winch)
- Sub-Type (Dyed / RFD / FB)
- Product Group (Cotton / Cotton Stretch / PC/PC Stretch / Bi-Stretch / Viscose/Modal / etc.)
- Count Band (Below 40s / 40s and above)
- Order Size Tier (≤500m / 501–3,000m / >3,000m)
- Buffer Rule: percentage and fixed minimum (e.g., "8% or 250m, whichever is higher")

Special rules displayed as explicit structured entries (not buried in comments):

- TAKISADA orders: +100m fixed
- Relax Dryer (XF finish): +1%
- HR / ET / T6S special finishes: +1%
- Jet / Jigger non-viscose: +4%
- Small-order overrides (≤500m): dedicated rate tier

#### 5.5.2 Version Control

Every update to the norm set creates a new immutable version:

- Version number (v68, v69, v70…), effective date, change summary, created by, approval status
- Versions are append-only — no retroactive edits once published
- Diff view between any two versions showing changed rules
- Current active version clearly marked; all previous versions accessible in read-only mode

#### 5.5.3 Norm Version Attachment

**Every sale order records the norms version ID active at order creation time.** This is a point-in-time snapshot — not a live link. Changes to norms never retroactively alter historical order records.

**Every article profile shows the norms version associated with its most recent analysis.**

Planners can revisit any historical order and view the exact norm rules that applied at that time — enabling accurate post-hoc audits and dispute resolution.

#### 5.5.4 Norm Revision Workflow

1. Manager proposes a new version in **Draft** state (editable)
2. Draft goes through a **Review / Approval** step
3. On approval, version is **Published** — becomes active for all new orders
4. Existing orders retain their original version reference

#### 5.5.5 AI-Driven Norm Recommendations

The intelligence engine continuously evaluates whether current norms match observed article performance:

- Articles where the AI-recommended buffer consistently differs from the active norm by >1% are surfaced as revision candidates
- Suggested rule changes displayed with supporting evidence (e.g., "Cotton 40s Soft Continuous: AI recommends 5.2% vs. current norm 6.0% — 93% of orders fulfilled at lower buffer")
- Managers can accept suggestions and auto-populate a new norm draft

---

### 5.6 Action Planning

Action Planning closes the loop between analytical insight and operational execution. It creates a structured cycle: **Insight → Action → Resolution → Impact Measurement.**

#### 5.6.1 Inline Action Suggestions (Contextual — Per Screen)

Every major screen surfaces contextually relevant action prompts derived from the intelligence engine. These are non-blocking suggestions — planners and managers can act, defer, or dismiss each one.

| Screen            | Trigger Condition                    | Example Prompt                                                                                       |
| ----------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Article Profile   | AI vs. norm divergence >1.5%         | *"Norms excessive for this article. Safe to reduce buffer by 2.3%. Create norm revision draft?"*   |
| Sale Order Detail | False Yield Warning triggered        | *"High yield but shortfall occurred — planning failure, not manufacturing. Add to review queue?"* |
| Sale Order Detail | Intervention ROI = Negative          | *"Planner reduced buffer below norm and caused shortfall. Flag for coaching review?"*              |
| Sale Order Detail | Reprocessing dependence >15%         | *"18% of delivery came from reprocessing. Investigate process quality for this article."*          |
| Route Dashboard   | Route shrinkage >2× fleet average   | *"Jet route shrinkage is 9.2% vs. fleet average 5.1%. Investigate process quality?"*               |
| Norms Dashboard   | Multiple articles showing divergence | *"8 articles have AI vs. norm gap >1.5%. Review for next norms revision cycle."*                   |
| Customer Profile  | Customer shortfall rate >15%         | *"Customer shortfall rate 22% vs. segment avg 8%. Review article mix and norms coverage."*         |

#### 5.6.2 Action Center (Standalone Interface)

A dedicated Action Center provides a consolidated view of all pending and completed actions across the organization.

**Action Inbox**

- All open action items with: source entity (article / order / customer / route / norms), severity (High / Medium / Low), recommended action type, assigned to, date created
- Filter by module, severity, assignee, date range, status

**Action Types**

| Type                            | Description                                                  |
| ------------------------------- | ------------------------------------------------------------ |
| **Norm Revision**         | Create a new norms draft based on AI recommendation          |
| **Order Review**          | Flag a sale order for planner or manager review              |
| **Planner Coaching**      | Flag a repeated pattern of negative Intervention ROI         |
| **Process Investigation** | Flag a route or article for quality team investigation       |
| **Article Watchlist**     | Monitor a volatile article through the next production cycle |

**Action Lifecycle**

```
Open → In Progress → Resolved / Dismissed
```

Each action records: created date, source insight, assigned to, resolution date, resolution notes.

**Action Analytics**

- Open vs. resolved actions over time
- Actions by type, by module, by assignee
- Impact tracking: after a Norm Revision action was resolved, did subsequent orders for that article improve?

---

## 6. Artificial Intelligence Engine

### 6.1 How the AI Learns

#### Learning from Historical Performance

The system analyzes every completed order to understand patterns:

**What Gets Analyzed:**

- Which buffer percentages consistently led to successful fulfillment
- How different article types behave during processing
- What factors influence success or failure (composition, route, finish, order size)
- Which planners' interventions helped vs. hurt outcomes

**Pattern Recognition:**

- Identifies articles with stable, predictable performance (HIGH elasticity)
- Flags articles with volatile, inconsistent performance (LOW elasticity)
- Detects when performance patterns shift over time
- Recognizes which routes or finishes are more prone to issues

**Success Classification:**

- Order is "successful" when: Pack Fresh ≥ Order Qty (customer order fulfilled)
- Order is "failure" when: Pack Fresh < Order Qty (shortfall, reprocessing needed)
- System focuses on learning from successful patterns

---

#### Continuous Improvement Mechanism

The system updates its understanding after each order completes:

**Update Cycle:**

```
1. Order Completes → Production outcome recorded
2. Calculate Result → Fulfilled or Shortfall?
3. Analyze Decision → Was reservation adequate? Did planner intervention help?
4. Update Patterns → Incorporate into article's historical profile
5. Refine Recommendations → Adjust future suggestions based on new data
6. Recalculate Confidence → Update reliability assessment
```

**Temporal Weighting:**

- Recent orders (last 6 months): Maximum influence on recommendations
- Mid-range orders (6-18 months): Moderate influence
- Older orders (18+ months): Lower influence but still considered
- Rationale: Recent performance better reflects current conditions

**Drift Detection:**
The system monitors when article behavior changes:

**Example Scenario:**

```
Article: Cotton 40s Soft Continuous
Historical Performance: 95% avg Fresh Yield (last 2 years)
Recent Performance: 88% avg Fresh Yield (last 3 months)

System Detection: "Yield drift detected - performance declining"
Action Triggered: Flag for process quality investigation
Recommendation Adjustment: Increase safety margin from 5.2% to 5.8%
```

---

#### Knowledge Transfer for New Articles

For new articles with limited or no history, the system leverages similarity to existing articles:

**Similarity Matching Process:**

1. **Extract New Article Characteristics:**

   - Composition: Cotton, PC, Viscose, etc.
   - Yarn Count: 40s, 60s, etc.
   - Route: Continuous, Jet, Jigger, Winch
   - Finish: Soft, Peach, Normal, etc.
   - Shade Type: Dyed, RFD, FB
   - Product Group: Cotton Stretch, Bi-Stretch, etc.
2. **Find Similar Articles:**

   - Search historical database for articles matching characteristics
   - Prioritize exact composition matches
   - Consider route and finish combinations
   - Evaluate order size patterns
3. **Transfer Performance Patterns:**

   - Retrieve successful buffer percentages from similar articles
   - Calculate weighted average based on similarity strength
   - Generate initial recommendation with LOW confidence
4. **Progressive Learning:**

   - After 5 direct orders: Begin article-specific learning (LOW confidence)
   - After 10 direct orders: Moderate confidence recommendations (MEDIUM)
   - After 50 direct orders: High confidence recommendations (HIGH)

**Example:**

```
New Article: Cotton Stretch 60s Peach Continuous
No Direct History Available

Similar Articles Found:
1. Cotton Stretch 40s Peach Continuous (45 orders, 82% success)
   - Typical buffer: 5.6%
   - Similarity score: 85% (different count)

2. Cotton 60s Peach Continuous (67 orders, 87% success)
   - Typical buffer: 5.1%
   - Similarity score: 80% (no stretch)

3. Cotton Stretch 60s Soft Continuous (34 orders, 79% success)
   - Typical buffer: 5.9%
   - Similarity score: 75% (different finish)

Weighted Recommendation: 5.5%
Confidence: LOW (no direct history)
Explanation: "Based on 3 similar articles with 146 total orders. 
Monitor first 5-10 orders closely and adjust if needed."
```

---

#### Confidence Measurement

The system provides transparency about recommendation reliability:

**Confidence Factors:**

1. **Data Volume:**

   - More historical orders = higher confidence
   - Minimum 5 orders required for article-specific recommendations
   - Optimal: 50+ orders for HIGH confidence
2. **Pattern Consistency:**

   - Low variance in successful buffer percentages = higher confidence
   - Example: If 80% of orders succeeded at 5.0%-5.5% buffer → HIGH consistency
   - Example: If orders succeeded at 3.5%, 4.2%, 6.8%, 5.1% → LOW consistency
3. **Recency:**

   - Recent orders available = higher confidence
   - All data older than 18 months = confidence reduced
4. **Success Rate:**

   - High historical success rate (>80%) = higher confidence
   - Low success rate (<60%) = lower confidence, flag for investigation

**Confidence Display:**

```
╔══════════════════════════════════════════════════════════════╗
║ AI RECOMMENDATION                                             ║
║                                                               ║
║ Optimal Reservation: 5.2%                                    ║
║ Current Norm: 6.0%                                           ║
║ Potential Improvement: 0.8% reduction (90m per 11,000m order)║
║                                                               ║
║ Confidence: ████████░░ HIGH (87/100)                         ║
║                                                               ║
║ Supporting Data:                                             ║
║ • 87 historical orders analyzed                              ║
║ • 74 orders succeeded (85% success rate)                     ║
║ • Typical successful range: 4.8% - 5.6%                      ║
║ • Pattern consistency: STRONG                                ║
║ • Most recent order: 12 days ago                             ║
║                                                               ║
║ Explanation:                                                 ║
║ 93% of historical orders fulfilled at 5.2% buffer.           ║
║ Current norm of 6.0% appears excessive, leading to           ║
║ average waste of 90 meters per order.                        ║
╚══════════════════════════════════════════════════════════════╝
```

---

#### Decision Balancing

The system optimizes recommendations for multiple objectives with clear priorities:

**Priority 1: Fulfill Customer Orders (Avoid Shortfalls)**

- Primary Goal: Ensure Pack Fresh ≥ Order Qty
- Impact: Shortfalls require costly reprocessing and delay delivery
- System Behavior: Adds safety margin when article has shortfall history
- Trade-off: Willing to accept minor waste to avoid shortfalls

**Priority 2: Minimize Fabric Waste (Avoid Excess)**

- Secondary Goal: Issue only what's needed, not more
- Impact: Excess issuance wastes expensive raw materials
- System Behavior: Reduces buffer when article consistently over-delivers
- Trade-off: Balances safety against material efficiency

**Priority 3: Reduce Reprocessing (First-Time Quality)**

- Tertiary Goal: Get it right the first time
- Impact: Reprocessing is costly, time-consuming, and inefficient
- System Behavior: Flags articles with high reprocessing for investigation
- Trade-off: May recommend process improvements over just higher buffers

**Balancing Logic:**

```
IF article has high shortfall rate (>15% of orders):
    → Priority 1 dominates: Recommend higher buffer with safety margin
  
ELSE IF article consistently over-delivers (surplus >5% on 80% of orders):
    → Priority 2 dominates: Recommend lower buffer to reduce waste
  
ELSE IF article has high reprocessing (>10% of delivery from reprocess):
    → Priority 3 dominates: Flag for process investigation, not just buffer increase
  
ELSE (stable, predictable performance):
    → Balanced optimization: Recommend buffer that fulfills 95% of orders
       with minimal waste
```

**Example Scenarios:**

**Scenario 1: High-Risk Article**

```
Article: Viscose Modal 60s Jet Dyed
Historical Performance: 65% success rate, frequent shortfalls
Current Norm: 6.0%
Historical successful range: 7.2% - 8.5%

AI Recommendation: 8.0% (higher than norm)
Reasoning: "Priority 1 - This article has high shortfall risk (35% failure rate).
           Recommend 8.0% buffer to ensure fulfillment. Consider process investigation."
Confidence: MEDIUM
```

**Scenario 2: Efficient Article**

```
Article: Cotton 40s Soft Continuous
Historical Performance: 92% success rate, consistent over-delivery
Current Norm: 6.0%
Historical successful range: 4.5% - 5.2%
Average surplus: 120 meters per order (5.8% waste)

AI Recommendation: 5.0% (lower than norm)
Reasoning: "Priority 2 - This article consistently over-delivers. Current norm wastes
           ~120m per order. Safe to reduce to 5.0% buffer while maintaining fulfillment."
Confidence: HIGH
```

**Scenario 3: Quality Issue Article**

```
Article: Cotton Stretch PC Jet Dyed
Historical Performance: 78% success rate
Reprocess Dependency: 18% of delivery from reprocessing
Average shrinkage: 9.2% (fleet average: 5.1%)

AI Recommendation: 6.5% buffer + FLAG FOR INVESTIGATION
Reasoning: "Priority 3 - High reprocessing indicates manufacturing quality issue,
           not planning issue. Recommend 6.5% buffer AND investigate Jet route
           process quality for this article type."
Confidence: MEDIUM
Action: Create Process Investigation task
```

---

### 6.2 Making Recommendations

#### Recommendation Generation Process

**Step-by-Step Flow:**

```
┌─────────────────────────────────────────┐
│ 1. ARTICLE IDENTIFICATION               │
│    Extract article characteristics      │
│    • Composition, Count, Route, Finish  │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 2. HISTORICAL RETRIEVAL                 │
│    Query database for all past orders   │
│    • Filter by article code             │
│    • Minimum 5 orders for direct        │
│    • Otherwise use similarity           │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 3. SUCCESS/FAILURE CLASSIFICATION       │
│    Separate orders by outcome           │
│    • Success: Pack Fresh ≥ Order Qty    │
│    • Failure: Pack Fresh < Order Qty    │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 4. PATTERN ANALYSIS                     │
│    Analyze successful orders            │
│    • Calculate buffer % for each        │
│    • Identify typical range             │
│    • Filter extreme outliers            │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 5. OPTIMAL BUFFER CALCULATION           │
│    Determine recommendation             │
│    • Central tendency of typical range  │
│    • Weight recent orders more          │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 6. SAFETY ADJUSTMENT                    │
│    Add appropriate margin               │
│    • Based on performance variability   │
│    • Consider shortfall risk            │
│    • Account for process quality        │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 7. CONFIDENCE ASSESSMENT                │
│    Evaluate reliability                 │
│    • Data volume (orders count)         │
│    • Pattern consistency                │
│    • Recency of data                    │
│    • Historical success rate            │
└────────────┬────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ 8. EXPLANATION GENERATION               │
│    Create plain-English reasoning       │
│    • Why this percentage?               │
│    • Supporting evidence                │
│    • Comparison to current norm         │
│    • Confidence level justification     │
└─────────────────────────────────────────┘
             ↓
┌─────────────────────────────────────────┐
│ FINAL RECOMMENDATION OUTPUT             │
│ • Optimal %                             │
│ • Confidence level                      │
│ • Explanation                           │
│ • Comparison to norm                    │
│ • Action suggestions                    │
└─────────────────────────────────────────┘
```

---

#### Detailed Example

**Article:** 18006BA — 100% Cotton 40s Soft Continuous

**Step 1: Article Identification**

```
Composition: 100% Cotton
Count: 40s
Route: Continuous
Finish: Soft
Shade: Dyed
Product Group: Cotton
```

**Step 2: Historical Retrieval**

```
Query Result: 87 orders found
Date Range: January 2024 - March 2026
Most Recent: 12 days ago
```

**Step 3: Classification**

```
Total Orders: 87
Successful: 74 orders (85.1%)
Failed: 13 orders (14.9%)
```

**Step 4: Pattern Analysis**

```
Successful Orders Buffer Analysis:
Minimum: 3.8%
Q1 (25th percentile): 4.8%
Median: 5.2%
Q3 (75th percentile): 5.6%
Maximum: 7.1%

Typical Range (Q1-Q3): 4.8% - 5.6%
[Excludes outliers: 3.8% (lucky) and 7.1% (wasteful)]
```

**Step 5: Optimal Buffer**

```
Central Value: 5.2% (median of typical range)
Recent Orders (last 6 months): 22 orders, median 5.1%
Weighted Calculation: (5.2% × 0.7) + (5.1% × 0.3) = 5.17%
Rounded: 5.2%
```

**Step 6: Safety Adjustment**

```
Performance Variability: Low (IQR = 0.8%)
Shortfall Risk: Low (85% success rate)
Process Quality: Good (avg shrinkage 4.2%, fleet avg 5.1%)

Safety Margin: +0.0% (already robust)
Final Recommendation: 5.2%
```

**Step 7: Confidence Assessment**

```
Data Volume: 87 orders ✓ (>50 = HIGH)
Pattern Consistency: Strong (IQR = 0.8%) ✓
Recency: 12 days ago ✓
Success Rate: 85% ✓

CONFIDENCE: HIGH (87/100)
```

**Step 8: Explanation**

```
"Based on 87 historical orders for this article, 74 orders (85%) 
successfully fulfilled at an average buffer of 5.2%. 

Typical successful range: 4.8% - 5.6%

Current norm: 6.0%

Recommendation: Use 5.2% buffer instead of 6.0%

Impact: Potential savings of 0.8% buffer = ~90 meters per 
11,000-meter order, without compromising fulfillment reliability.

Historical evidence strongly supports this recommendation."
```

---

### 6.3 Handling New Articles

For articles with limited or no historical data, the system provides two approaches:

#### Approach 1: Sequential Learning (Gradual Data Accumulation)

**When to Use:** New articles being introduced to production gradually

**How It Works:**

**Initial State (0-4 Orders):**

- System uses standard planning rules as baseline
- No article-specific AI recommendation yet
- Fallback message: "Insufficient data. Using planning norm: 6.0%"

**Early Learning (5-9 Orders):**

- System begins generating recommendations
- Confidence: LOW
- Initial pattern recognition from limited data
- Recommendation includes large safety margin
- Display: "Early learning mode - monitor outcomes closely"

**Developing (10-49 Orders):**

- Patterns become clearer
- Confidence: MEDIUM
- Recommendations more refined
- Safety margin reduces as data grows
- Display: "Moderate confidence - based on 23 orders"

**Mature (50+ Orders):**

- Full confidence achieved
- Confidence: HIGH
- Recommendations fully optimized
- Standard safety margins applied
- Display: "High confidence - based on 67 orders"

**Timeline Example:**

```
Month 1-2: Orders 1-4
   → Using planning norm 6.0%
   → System observing: 3 successes, 1 shortfall

Month 3: Order 5
   → AI activates: "Recommend 6.5% (LOW confidence - 5 orders)"
   → Higher margin due to limited data

Month 4-6: Orders 6-15
   → Confidence improves: "Recommend 5.8% (MEDIUM confidence - 15 orders)"
   → Patterns emerging

Month 12: Order 50
   → Full confidence: "Recommend 5.3% (HIGH confidence - 50 orders)"
   → Fully optimized
```

---

#### Approach 2: Composition-Based Prediction (Similarity Transfer)

**When to Use:** Need immediate guidance for new article before accumulating orders

**How It Works:**

**Step 1: Input Article Parameters** (20 key characteristics)

```
Planner provides:
1. Composition (Cotton, PC, Viscose, etc.)
2. Composition %: (e.g., 60% Cotton / 40% Polyester)
3. Yarn Count (40s, 60s, etc.)
4. Yarn Type (Combed, Carded, Ring Spun)
5. Processing Route (Continuous, Jet, Jigger, Winch)
6. Finish Type (Soft, Peach, Normal, etc.)
7. Shade Type (Dyed, RFD, FB)
8. Fabric Construction (Plain, Twill, Satin)
9. Fabric Weight (GSM)
10. Width (inches)
11. Order Size (typical expected order size)
12. Customer Segment (Domestic, Export)
13. End Use (Shirting, Suiting, etc.)
14. Special Treatments (Mercerized, Sanforized, etc.)
15. Dyeing Method (Reactive, Vat, etc.)
16. Quality Grade (Premium, Standard, Economy)
17. Stretch Type (if applicable: 2-way, 4-way, None)
18. Print Type (Solid, Printed, Y/D)
19. Expected Volume (Annual meters)
20. Priority Level (Urgent, Standard)
```

**Step 2: Similarity Matching**

```
System searches database for articles matching characteristics:

Exact Match Priority:
1. Composition + Count + Route + Finish (100% match)
2. Composition + Count + Route (90% match)
3. Composition + Count (80% match)
4. Composition + Route (70% match)

Partial Match Weighting:
- Composition match: 40% weight
- Route match: 25% weight
- Finish match: 15% weight
- Count match: 10% weight
- Order size match: 10% weight
```

**Step 3: Pattern Transfer**

```
System retrieves performance data from similar articles:

Example Output:
Found 5 similar articles:

1. Cotton 40s Soft Continuous (87 orders, 85% success)
   Similarity: 95% (exact except different product code)
   Typical buffer: 5.2%

2. Cotton Stretch 40s Soft Continuous (45 orders, 82% success)
   Similarity: 85% (stretch variant)
   Typical buffer: 5.6%

3. Cotton 60s Soft Continuous (67 orders, 87% success)
   Similarity: 80% (different count)
   Typical buffer: 5.0%

4. Cotton 40s Peach Continuous (56 orders, 80% success)
   Similarity: 75% (different finish)
   Typical buffer: 5.4%

5. Cotton 40s Soft Jet (34 orders, 79% success)
   Similarity: 70% (different route)
   Typical buffer: 6.1%
```

**Step 4: Generate Initial Recommendation**

```
Weighted Average:
(5.2% × 0.95) + (5.6% × 0.85) + (5.0% × 0.80) + 
(5.4% × 0.75) + (6.1% × 0.70) / (0.95+0.85+0.80+0.75+0.70)

= 5.4%

Add Safety Margin: +0.3% (for uncertainty)

Initial Recommendation: 5.7%
Confidence: LOW (no direct history)

Display:
"Based on 5 similar articles with 289 total orders.
Strong match to Cotton 40s Soft Continuous (95% similar).
Start with 5.7% and monitor first 5-10 orders closely."
```

**Step 5: Progressive Refinement**

```
As Direct Data Accumulates:

Order 1-4: Use similarity-based 5.7%
Order 5: Blend similarity (70%) + direct data (30%) → 5.6%
Order 10: Blend similarity (50%) + direct data (50%) → 5.5%
Order 20: Blend similarity (30%) + direct data (70%) → 5.4%
Order 50+: Pure direct data → 5.3% (HIGH confidence)
```

---

#### Comparison: Approach 1 vs. Approach 2

| Aspect                       | Approach 1: Sequential         | Approach 2: Composition-Based     |
| ---------------------------- | ------------------------------ | --------------------------------- |
| **Setup Required**     | None                           | 20 parameters input               |
| **Immediate Guidance** | No (uses norm)                 | Yes (similarity-based)            |
| **Initial Accuracy**   | Depends on norm                | Depends on similarity quality     |
| **Data Requirements**  | Wait for 5+ orders             | Similar articles must exist       |
| **User Effort**        | Low                            | Moderate (one-time setup)         |
| **Best For**           | Standard articles, low urgency | Critical articles, immediate need |

---

### 6.4 Continuous Improvement

#### Learning Cycle

The system operates on a continuous learning cycle:

```
┌──────────────────────────────────────────────────────┐
│                 CONTINUOUS LEARNING CYCLE             │
└──────────────────────────────────────────────────────┘

1. NEW ORDER ARRIVES
   ↓
2. AI GENERATES RECOMMENDATION
   (Based on current knowledge)
   ↓
3. PLANNER MAKES DECISION
   (May accept, adjust, or override AI)
   ↓
4. PRODUCTION EXECUTES
   (Fabric issued, processed, packed)
   ↓
5. OUTCOME RECORDED
   (Pack Fresh vs. Order Qty measured)
   ↓
6. SYSTEM ANALYZES RESULT
   • Was order fulfilled?
   • Was AI recommendation adequate?
   • Did planner's adjustment help or hurt?
   • What was actual Fresh Yield?
   ↓
7. KNOWLEDGE UPDATED
   • Article historical profile updated
   • Confidence recalculated
   • Pattern consistency re-evaluated
   ↓
8. RECOMMENDATIONS REFINED
   (Next order gets improved recommendation)
   ↓
   [Loop back to step 1]
```

---

#### What the System Learns

**Article-Level Learning:**

- Typical buffer percentages that lead to success
- Performance variability (stable vs. volatile)
- Seasonal patterns (if any)
- Sensitivity to order size
- Processing efficiency trends

**Route-Level Learning:**

- Which routes have higher shrinkage
- Route-specific quality issues
- Comparative performance across routes

**Planner-Level Learning:**

- When planner overrides help outcomes
- When planner overrides hurt outcomes
- Individual planner risk tolerance patterns
- Coaching opportunities

**Process-Level Learning:**

- Manufacturing efficiency trends
- Quality issue identification
- Reprocessing patterns
- Root cause indicators

**Customer-Level Learning:**

- Segment-specific fulfillment rates
- Customer tolerance for shortfalls
- Order pattern characteristics

---

#### Improvement Measurement

The system tracks improvement over time:

**Key Metrics:**

```
Fulfillment Rate:
Before AI: 78% of orders fulfilled on first run
After 6 months: 86% of orders fulfilled
After 12 months: 91% of orders fulfilled

Waste Reduction:
Before AI: Average 6.8% buffer issued
After 6 months: Average 5.9% buffer
After 12 months: Average 5.4% buffer

Reprocessing:
Before AI: 18% of orders required reprocessing
After 6 months: 12% required reprocessing
After 12 months: 8% required reprocessing
```

**Dashboard Display:**

```
╔════════════════════════════════════════════════════╗
║ SYSTEM IMPROVEMENT TRACKING                         ║
║                                                     ║
║ Since System Deployment: 12 months                  ║
║                                                     ║
║ Fulfillment Rate:       78% → 91% (+13%)           ║
║ Average Buffer:         6.8% → 5.4% (-1.4%)        ║
║ Reprocessing Rate:      18% → 8% (-10%)            ║
║                                                     ║
║ Estimated Savings:      ₹2.4 Cr annually           ║
║ Material Saved:         14,500 meters per month     ║
║ Reprocess Cost Avoided: ₹45 L per month            ║
╚════════════════════════════════════════════════════╝
```

---

### 6.5 Confidence & Explainability

#### Confidence Indicators

The system provides clear confidence levels with every recommendation:

**Confidence Levels:**

| Level                 | Criteria                                     | Display Color | User Guidance                              |
| --------------------- | -------------------------------------------- | ------------- | ------------------------------------------ |
| **HIGH**        | 50+ orders, consistent patterns, recent data | Green         | "Reliable recommendation - safe to follow" |
| **MEDIUM**      | 10-49 orders, moderate consistency           | Yellow        | "Reasonable confidence - monitor outcome"  |
| **LOW**         | 5-9 orders or inconsistent patterns          | Orange        | "Limited data - use with caution"          |
| **NEW ARTICLE** | <5 orders, using similarity                  | Red           | "Preliminary guidance - monitor closely"   |

**Confidence Breakdown:**

```
╔═══════════════════════════════════════════════════════╗
║ CONFIDENCE ASSESSMENT                                  ║
║                                                        ║
║ Overall: ████████░░ HIGH (87/100)                     ║
║                                                        ║
║ Contributing Factors:                                 ║
║                                                        ║
║ Data Volume:           ██████████ 100/100             ║
║   87 orders (>50 threshold)                           ║
║                                                        ║
║ Pattern Consistency:   ████████░░ 85/100              ║
║   Strong (IQR = 0.8%, success range tight)            ║
║                                                        ║
║ Data Recency:          ██████████ 95/100              ║
║   Most recent order: 12 days ago                      ║
║                                                        ║
║ Success Rate:          ████████░░ 85/100              ║
║   74 of 87 orders (85%) fulfilled                     ║
║                                                        ║
║ Process Stability:     █████████░ 90/100              ║
║   Shrinkage stable, no quality alerts                 ║
╚═══════════════════════════════════════════════════════╝
```

---

#### Explanations Provided

Every recommendation includes a plain-English explanation:

**Components of Explanation:**

1. **What is recommended**

   - Specific buffer percentage
   - Expected outcome if followed
2. **Why this recommendation**

   - Number of orders analyzed
   - Success rate of historical orders
   - Typical successful range
3. **Comparison to current practice**

   - Current planning norm
   - Difference and impact
   - Potential improvement
4. **Supporting evidence**

   - Most recent order outcome
   - Pattern consistency notes
   - Any risk factors or alerts
5. **Action suggestion**

   - What to do with this recommendation
   - Monitoring advice
   - Follow-up actions

**Example Full Explanation:**

```
╔══════════════════════════════════════════════════════════════╗
║ AI RECOMMENDATION EXPLANATION                                 ║
║ Article: 18006BA — Cotton 40s Soft Continuous                 ║
╠══════════════════════════════════════════════════════════════╣
║                                                               ║
║ RECOMMENDATION: 5.2% buffer                                   ║
║                                                               ║
║ EXPECTED OUTCOME:                                            ║
║ For an 11,000-meter order, issue 11,572 meters               ║
║ 95% probability of fulfillment on first run                  ║
║                                                               ║
║ ─────────────────────────────────────────────────────────── ║
║                                                               ║
║ WHY 5.2%?                                                    ║
║                                                               ║
║ We analyzed 87 historical orders for this article:           ║
║                                                               ║
║ • 74 orders (85%) successfully fulfilled                     ║
║ • These successful orders used buffers ranging from          ║
║   4.8% to 5.6% (typical range)                              ║
║ • The most common successful buffer: 5.2%                    ║
║ • Most recent order (12 days ago): Used 5.1%, succeeded     ║
║                                                               ║
║ Pattern Consistency: STRONG                                   ║
║ Performance is predictable and stable for this article.       ║
║                                                               ║
║ ─────────────────────────────────────────────────────────── ║
║                                                               ║
║ COMPARISON TO CURRENT NORM:                                   ║
║                                                               ║
║ Current Planning Norm: 6.0%                                   ║
║ AI Recommendation:     5.2%                                   ║
║ Difference:            -0.8%                                  ║
║                                                               ║
║ IMPACT:                                                       ║
║ For typical 11,000-meter order:                              ║
║ • Current norm issues: 11,660 meters                         ║
║ • AI recommends:      11,572 meters                          ║
║ • Potential savings:  88 meters per order                    ║
║                                                               ║
║ At ₹250 per meter: ₹22,000 savings per order                ║
║                                                               ║
║ Historical Evidence:                                          ║
║ 93% of past orders fulfilled successfully at 5.2% buffer     ║
║ or lower, suggesting current 6.0% norm is excessive.         ║
║                                                               ║
║ ─────────────────────────────────────────────────────────── ║
║                                                               ║
║ CONFIDENCE: HIGH                                              ║
║ This recommendation is based on strong historical evidence    ║
║ with consistent patterns.                                     ║
║                                                               ║
║ ─────────────────────────────────────────────────────────── ║
║                                                               ║
║ SUGGESTED ACTION:                                             ║
║                                                               ║
║ ✓ Use 5.2% buffer for this article going forward             ║
║ ✓ Consider revising planning norm from 6.0% to 5.2%          ║
║ ✓ Monitor next 3-5 orders to confirm continued success       ║
║                                                               ║
║ This article has stable, predictable performance.            ║
║ Safe to follow this recommendation.                           ║
║                                                               ║
╚══════════════════════════════════════════════════════════════╝
```

---

#### Meta-Learning vs. Human Hit & Trial

The system introduces a fundamental shift in how we learn from failures:

| Traditional Approach (Human Hit & Trial)                | AI System Approach (Meta-Learning)                            |
| ------------------------------------------------------- | ------------------------------------------------------------- |
| Each planner learns from their own limited experience   | System learns from ALL failed orders across entire database   |
| Knowledge is siloed and inconsistent                    | Collective intelligence — patterns from hundreds of articles |
| Learning is slow — requires personal repeated failures | Instant knowledge transfer from all historical failures       |
| Every new article starts from scratch                   | Meta-learner transfers knowledge from similar failed articles |
| No comparison baseline                                  | Shows "Human Route vs. AI Route" for every failed order       |
| Relies on individual memory and judgment                | Data-driven pattern recognition across thousands of orders    |

**Example Comparison for Failed Orders:**

```
╔════════════════════════════════════════════════════════════╗
║ ORDER ANALYSIS: F81-24002345 (SHORTFALL)                   ║
╠════════════════════════════════════════════════════════════╣
║                                                             ║
║ Article: Cotton Stretch 60s Jet Dyed                       ║
║ Order Qty: 10,000 meters                                   ║
║ Outcome: Pack Fresh 9,200 meters (800m SHORTFALL)          ║
║                                                             ║
║ ──────────────────────────────────────────────────────────║
║                                                             ║
║ WHAT ACTUALLY HAPPENED (Human Decision):                   ║
║                                                             ║
║ Planner issued: 10,500 meters (5.0% buffer)                ║
║ Reasoning: "Used standard norm"                            ║
║ Result: FAILED - shortfall of 800 meters                   ║
║                                                             ║
║ ──────────────────────────────────────────────────────────║
║                                                             ║
║ WHAT AI WOULD HAVE RECOMMENDED (Data-Driven):             ║
║                                                             ║
║ AI recommendation: 10,750 meters (7.5% buffer)             ║
║ Reasoning: "Based on 12 similar articles with 187 orders  ║
║            that had same Jet + Stretch combination.        ║
║            These typically require 7-8% due to higher      ║
║            shrinkage and processing loss."                 ║
║                                                             ║
║ If followed: Would have issued 250m more                   ║
║ Expected outcome: SUCCESS (fulfilled with minor surplus)    ║
║                                                             ║
║ ──────────────────────────────────────────────────────────║
║                                                             ║
║ KEY LEARNING:                                               ║
║                                                             ║
║ Human approach: Applied generic 5% norm                     ║
║ Problem: Didn't account for Jet + Stretch combination      ║
║                                                             ║
║ AI approach: Recognized pattern from 187 similar orders    ║
║ Advantage: Knew this combo needs 7.5% from collective data ║
║                                                             ║
║ ──────────────────────────────────────────────────────────║
║                                                             ║
║ LESSON FOR FUTURE:                                          ║
║                                                             ║
║ Human learning: This planner now knows for next time       ║
║ (But only this one planner learns)                         ║
║                                                             ║
║ AI learning: System updates patterns for ALL planners      ║
║ Next time ANY planner gets this article combo:             ║
║ → AI will recommend 7.5% automatically                     ║
║ → All planners benefit from this one failure               ║
║                                                             ║
╚════════════════════════════════════════════════════════════╝
```

**Systematic Advantages of Meta-Learning:**

1. **Collective Intelligence:**

   - Human: One planner's experience
   - AI: All planners' collective experience
2. **Pattern Recognition:**

   - Human: May not recognize subtle patterns (Jet + Stretch)
   - AI: Recognizes complex multi-factor patterns automatically
3. **Knowledge Transfer:**

   - Human: Knowledge stays with individual
   - AI: Knowledge instantly available to entire organization
4. **Learning Speed:**

   - Human: Requires multiple personal failures
   - AI: Learns from first occurrence, any planner
5. **Consistency:**

   - Human: Varies by planner experience
   - AI: Same high-quality recommendation for everyone

**Meta-Learning in Practice:**

When system encounters a failure:

```
1. Record Failure Details:
   - What article characteristics?
   - What buffer was used?
   - What was the outcome?
   - What factors were present?

2. Update Pattern Database:
   - Add to article's failure history
   - Update characteristic patterns (Route, Finish, Stretch, etc.)
   - Recalculate recommendations

3. Cross-Reference Similarities:
   - Find all articles with similar characteristics
   - Update recommendations for entire similarity group

4. Propagate Learning:
   - Next order with same characteristics → Higher buffer recommended
   - ALL planners get updated recommendation
   - Learning happens once, benefits everyone

Result: One failure teaches the entire system
```

---

## 7. System Requirements

### 7.1 Role-Based Access Control

| Role              | Permissions                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| **Planner** | View all modules, create and update sale orders and actions, cannot draft or publish norms                  |
| **Manager** | All planner permissions + approve/publish norm revisions, view planner execution dashboards, assign actions |
| **Admin**   | Full access including user management, data import/export configuration, system settings                    |

### 7.2 Norms Version Integrity

- Norms versions are strictly append-only once published
- Every sale order record stores `norms_version_id` at creation — immutable for the life of that order
- All historical analytics correctly identify which norm version was active during any time window
- Retroactive norm changes never affect historical order records

### 7.3 Performance Standards

| Operation                                           | Target Performance |
| --------------------------------------------------- | ------------------ |
| Article / Order list load                           | < 500ms            |
| Sale order detail (all metrics + waterfall + blame) | < 500ms            |
| AI recommendation generation                        | < 200ms            |
| Dashboard aggregations                              | < 2 seconds        |
| Planning rule lookup                                | < 50ms             |

### 7.4 Data Export & Integration

All tables and dashboards are exportable to Excel. Export formats match the existing data structure familiar to Vardhman planners to ensure smooth adoption.

**Integration Modes:**

- **Excel Upload/Download:** Manual operations for ad-hoc analysis and backup
- **NOW System Integration:** Automated real-time sync with Vardhman's NOW system

---

## 8. Glossary

| Term                             | Definition                                                                                                                         |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Article**                | Unique fabric identifier combining construction, yarn count, and product type (e.g., "18006BA — 100% Cotton 40s Soft Continuous") |
| **Sale Order (COPS_NO)**   | Customer purchase order; may span multiple order lines                                                                             |
| **PO (Production Order)**  | Individual production batch within a sale order line                                                                               |
| **Fresh PO**               | First-run production PO — primary fulfillment mechanism                                                                           |
| **Reprocess PO (FRG/FRP)** | Corrective production run for defective or under-yielded fabric                                                                    |
| **Order Qty (DORQT1)**     | Customer-requested quantity in meters — the ground truth target                                                                   |
| **Reserved Qty (RES_QTY)** | Greige quantity calculated by applying norm rules to Order Qty                                                                     |
| **Issued Qty (ISS_QTY)**   | Actual greige physically issued to production (manual; constrained by inventory)                                                   |
| **Pack Fresh**             | Quantity packed at first-run quality — the true output metric                                                                     |
| **Total Packing**          | All packed quantity including reprocessed fabric                                                                                   |
| **Fresh Yield %**          | Pack Fresh ÷ Fresh Issued × 100 — primary production efficiency metric                                                          |
| **Shortfall**              | Order Qty − Pack Fresh when positive — quantity not fulfilled by first run                                                       |
| **Norm / Norm Rule**       | A buffer rule specifying how much extra greige to reserve for a given article category                                             |
| **Norms Version**          | Immutable, dated snapshot of the complete norm rule set                                                                            |
| **Waterfall**              | Step-down chart: Demand → Policy Gap → Execution Adj → Process Loss → Delivered                                                |
| **Blame Attribution**      | Quantified share of variance attributed to Policy (norms), Execution (planner), Process (manufacturing)                            |
| **Intervention ROI**       | Assessment of whether a planner's deviation from norms helped, was neutral, or caused harm                                         |
| **False Yield Warning**    | Alert when Fresh Yield is high but a shortfall still occurred — indicates under-issuance, not manufacturing failure               |
| **Action**                 | A recommended follow-up task generated by the intelligence engine from an insight                                                  |
| **Route**                  | Processing machine type: Continuous, Jet, Jigger, Winch                                                                            |
| **Shade Type**             | Dyed, RFD (Ready for Dyeing), FB (Full Bleach)                                                                                     |
| **Elasticity**             | Yield stability classification: HIGH (≥90%), MEDIUM (80–90%), LOW (<80%)                                                         |
| **Confidence Level**       | System's assessment of recommendation reliability based on data volume, pattern consistency, and recency                           |
| **Knowledge Transfer**     | System's ability to apply patterns from similar articles to new articles with limited history                                      |

---

## 7. Business Impact Analysis

This section provides quantitative analysis of current operational performance, identifying key problem areas and improvement opportunities that the CRM system addresses through intelligence-driven decision making.

### 7.1 Current Performance Metrics

Based on analysis of **4,613 historical production orders** across **970 unique sale orders** and **486 unique articles**:

| KPI                                     | Value             | Business Meaning                     |
| --------------------------------------- | ----------------- | ------------------------------------ |
| **Total Production Orders (POs)** | 4,613             | Total manufacturing orders processed |
| **Unique Sale Orders**            | 970               | Customer orders received             |
| **Unique Articles**               | 486               | Different fabric types processed     |
| **Total Greige Issued**           | 13,975,906 meters | Raw material issued to production    |
| **Total Fresh Packed**            | 12,322,706 meters | First-quality output delivered       |
| **Overall Loss**                  | 11.8%             | Material lost during processing      |

### 7.2 Shortfall Analysis

**Shortfall** occurs when `Pack Fresh < Order Qty` — the fabric produced was less than what the customer ordered, requiring costly reprocessing.

| Metric                          | Value                      | Impact                                      |
| ------------------------------- | -------------------------- | ------------------------------------------- |
| **Orders with Shortfall** | 368 / 970 =**37.9%** | More than 1 in 3 orders fail to meet demand |
| **Total Shortfall**       | 1,029,677 meters           | Fabric shortfall across all orders          |
| **Average Shortfall**     | 2,798 meters per order     | Average deficit when order fails            |

**Business Impact:**

- Customer orders under-fulfilled
- Requires reprocessing to meet demand
- Additional production costs
- Potential delivery delays

### 7.3 Excess Buffer Analysis

**Excess Buffer** occurs when `Issued Qty >> Order Qty` — more raw material issued than needed, resulting in waste.

| Metric                              | Value                      | Impact                                |
| ----------------------------------- | -------------------------- | ------------------------------------- |
| **Orders with Excess Buffer** | 892 / 970 =**92.0%** | Nearly all orders have extra material |
| **Total Excess Material**     | 1,553,821 meters           | Raw material issued but not needed    |
| **Average Excess**            | 1,742 meters per order     | Average waste per order               |
| **Orders with >10% Buffer**   | 373 / 970 =**38.5%** | Significant over-issue                |

**Business Impact:**

- Wasted expensive raw material (cotton, Tencel, etc.)
- Deadstock — excess fabric with no immediate use
- Working capital tied up in inventory

### 7.4 Estimated Savings Opportunity

If buffers are optimized using AI-driven recommendations:

| Metric                    | Current          | With Optimization               | Savings                   |
| ------------------------- | ---------------- | ------------------------------- | ------------------------- |
| **Excess Material** | 1,553,821 meters | ~776,910 meters (50% reduction) | **~777,000 meters** |
| **Average Buffer**  | 12.9%            | ~6-8% (target)                  | **4-6% per order**  |

### 7.5 Route Performance Analysis

Different processing routes have significantly different yields:

| Route                          | Orders | Yield % | Status           |
| ------------------------------ | ------ | ------- | ---------------- |
| **Continuous**           | 910    | 89.1%   | Best performer   |
| **Continuous (variant)** | 5      | 90.6%   | Excellent        |
| **Jigger**               | 44     | 78.1%   | Needs attention  |
| **Jet**                  | 19     | 71.2%   | Poor performance |

**Key Insight:** Jet and Jigger routes have significantly lower yields (71-78%) compared to Continuous (89%). The intelligence engine learns route-specific patterns and provides differentiated recommendations based on these performance characteristics.

### 7.6 Article Performance Distribution

Articles exhibit varying performance characteristics that the AI recommendation engine analyzes:

- **High-Performing Articles:** Consistent yields ≥95%, predictable behavior, lower buffer requirements
- **Medium-Performing Articles:** Yields between 85-95%, moderate variability, standard buffers adequate
- **Low-Performing Articles:** Yields <85%, high variability, require investigation or higher buffers

The CRM system tracks article-level performance and surfaces actionable insights through the Article Management module and Action Planning center.

---

**End of Technical Requirements Document**